Updating Data Through the API

Suggest Edits

When updating data there are several key rules to follow.

  1. Identify the object that needs updating.
  2. Don't forget the entity/document ID inside the payload too.
  3. Update only what is required, and no more.

1. Identify the object that needs updating

An entityId, documentId, addressId or scanDocId must be supplied if a specific item is being updated.

If an ID is not supplied, the service will assume you are attempting to add a new document/address/document scan.

For example, if you have a recently added entity like so:

{
  "entityId": "12345678-4321-1234-4321-123456789012",
  "name": {
    "familyName": "DOE",
    "middleNames": "DAVID",
    "givenName": "JOHN",
    "displayName": “J DOE”
  },
  "addresses": [
    {
      "addressId": "876543231-1234-4321-1234-210987654321",
      "streetNumber": "12",
      "streetName": "Smith St",
      "town": "Smithville",
      "postalCode": "1234",
      "state": "VIC",
      "country": "AUS"
    }
  ]
}

If you wish to update the above address to 15 Smith Rd, Jonestown NSW 2345, you would send a payload of:

{
  "entityId": "12345678-4321-1234-4321-123456789012",
  "addresses": [
    {
      "addressId": "876543231-1234-4321-1234-210987654321",
      "streetNumber": "15",
      "streetName": "Smith Rd",
      "town": "Jonestown",
      "postalCode": "2345",
      "state": "NSW",
      "country": "AUS"
    }
  ]
}

If you just sent:

{
  "entityId": "12345678-4321-1234-4321-123456789012",
  "addresses": [
    {
      "streetNumber": "15",
      "streetName": "Smith Rd",
      "town": "Jonestown",
      "postalCode": "2345",
      "state": "NSW",
      "country": "AUS"
    }
  ]
}

i.e. without the addressId, then the service will assume you’re adding another address, and you would end up with:

{
  "entityId": "12345678-4321-1234-4321-123456789012",
  "name": {
    "familyName": "DOE",
    "middleNames": "DAVID",
    "givenName": "JOHN",
    "displayName": “J DOE”
  },
  "addresses": [
    {
      "addressId": "876543231-1234-4321-1234-210987654321",
      "streetNumber": "12",
      "streetName": "Smith St",
      "town": "Smithville",
      "postalCode": "1234",
      "state": "VIC",
      "country": "AUS"
    },
    {
      "addressId": "77777777-1111-2222-3333-444444444444",
      "streetNumber": "15",
      "streetName": "Smith Rd",
      "town": "Jonestown",
      "postalCode": "2345",
      "state": "NSW",
      "country": "AUS"
    }
  ]
}

2. Don't forget the entity/document ID inside the payload too.

When calling the update entity and document endpoints, you must specify the entity/document ID in both the URI AND the JSON document as well. These must match, otherwise, an error will be returned.

i.e.,

POST https://api.demo.frankiefinancial.io/compliance/v1.2/entity/12345678-4321-1234-4321-123456789012

{
  "entityId": "12345678-4321-1234-4321-123456789012",
  "name": {
    "familyName": "DOE",
    "middleNames": "DAVID",
    "givenName": "JOHN",
    "displayName": “J DOE”
  },
...

(We actually apologize for this, it's a historical factor that will be removed in the next major release).

3. Update only what is required, and no more.

You only need to supply the data you wish to update, but if you are updating an object, you need to supply all of the object information.

The Frankie service will do its best to merge data and treat the update like a PATCH request, rather than a replacement, but this granularity will only go so far.

For example, if you are updating the name object of an entity, you will need to supply ALL of the name elements, not just the field you are updating.

So if you have someone named JANE LISA DOE, and you wish to change their name to JOHN DAVID DOE, you would need to send:

{
  “familyName”: “DOE”,
  “middleNames”: “DAVID”,
  “givenName”: “JOHN”,
  “displayName”: “J DOE”
}

rather than just:

{
 “middleNames”: “DAVID”,
 “givenName”: “JOHN”
}

If you aren’t modifying an object, you don’t need to re-send the data.

This means that if you have an entity with 3 embedded documents, and you only wish to modify one of them, then you don’t need to send anything else (name, addresses, other documents). You could just send:

{
  "entityId": "84a9a860-68ae-4d7d-9a53-54a1116d5051",
  "identityDocs": [
    {
      "documentId": "84a9a860-68ae-4d7d-9a53-54a1116d5052",
      "idType": "DRIVERS_LICENCE",
      "country": "AUS",
      "region": "VIC",
      "idNumber": "123456789"
    }
  ]
}

🚧

Spacial Case: Key-Value-Pairs

KVPs are a special case.
Because they don’t have individual IDs, the update process will use an “UPSERT” model.
So if there is an existing KVP with the same name, it will be replaced. Otherwise it is added to the list.

Updated 4 months ago