Updating Data Through the API

When updating data you need to ensure you follow several key rules.

  1. Identify the object you want to update
  2. Don't forget the entity / document ID inside the payload too.
  3. Update only what you need, and no more

1. Identify the object you want to update

You must always supply an entityId, documentId, addressId or scanDocId if you are updating a specific item.

If you don’t specify an ID, the service will assume you’re 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 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 apologise for this - it's a historical factor that will be removed in the next major release).

3. Update only what you need, 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, 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.


Did this page help you?