External identifiers

Some resources have external identifiers, fields holding unique identifiers in external systems. These values can be used in all requests on a par with internal UUIDs.

Suppose you have a database with a customers table

Table 1. customers

Field

Type

Null?

Description

id

integer

not null

Primary key

first_name

varchar(50)

not null

second_name

varchar(50)

not null

address

varchar(500)

phone

varchar(100)

To replicate customers rows as clients in Planado you can use customers.id values as external identifiers.

Say we have a record

{
  "id": 42,
  "first_name": "John",
  "last_name": "Doe",
  "address": "26 Ridge St. Fresh Meadows, NY 11365",
  "phone": "(576) 241-4209"
}

To post or update it in Planado you can use the same request relying on 42 to be a unique external identifier

$ curl -H "X-Planado-API-Key:XXX" \
       -X PATCH \
       https://api.planadoapp.com/v2/clients/42 \
       --data @- << EOF | jq
{
  "organization": false,
  "first_name": "John",
  "last_name": "Doe",
  "address": {
    "formatted": "26 Ridge St. Fresh Meadows, NY 11365"
  },
  "contacts": [
    {
      "value": "(576) 241-4209",
      "type": "phone"
    }
  ]
}
EOF
{
  "client_uuid": "40a10224-890d-4fca-8f46-1eef1102dc28"
}

This saves you from checks if a client is already present in Planado.