Skip to main content

Resource Record APIs

Use the resource record APIs to add structured data to a Flowcall resource or update an existing record using one of its fields as an identifier.

Authentication​

Create an access token from Settings -> Integrations in the Flowcall dashboard.

Pass the token as a Bearer token in every request:

Authorization: Bearer <your_access_token>

The access token determines the Flowcall account. The requested resource must belong to that account.

Insert a record​

Adds a new record every time it is called. Use upsert instead when repeated calls for the same identifier should update the existing record.

POST https://api.flowcall.co/apis/resources/records/insert

Request body​

FieldTypeRequiredDescription
objectIdstringYesID of the resource object that will receive the record.
dataobjectYesResource values keyed by the field keys configured on the object.

Required resource fields must be included. Unknown fields and values that cannot be converted to the configured field type return an error.

Example request​

The following example inserts a row into the order data resource:

curl -X POST https://api.flowcall.co/apis/resources/records/insert \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "objectId": "3249970d-e728-4dad-9659-f8fd810c5e4b",
    "data": {
      "order_name": "#ORDER-123",
      "return_type": "exchange",
      "return_shipment_awb": "AWB123456",
      "return_shipment_status": "picked_up"
    }
  }'

Success response​

{
  "success": true,
  "record": {
    "id": "<resource_record_id>",
    "objectId": "3249970d-e728-4dad-9659-f8fd810c5e4b",
    "customerId": null,
    "data": {
      "order_name": "#ORDER-123",
      "return_type": "exchange",
      "return_shipment_awb": "AWB123456",
      "return_shipment_status": "picked_up"
    },
    "createdAt": "2026-08-07T10:00:00.000Z",
    "updatedAt": "2026-08-07T10:00:00.000Z"
  },
  "conflicts": [],
  "conflictCount": 0
}

Upsert a record​

Finds a record by an exact resource-field value. If one record matches, Flowcall merges the supplied data into it. If no record matches, Flowcall inserts a new record.

POST https://api.flowcall.co/apis/resources/records/upsert

Request body​

FieldTypeRequiredDescription
objectIdstringYesID of the resource object that will receive the record.
idFieldstringYesResource field key used to find the existing record.
idValueanyYesExact value to match in idField. It is converted using the field's type.
dataobjectYesValues to insert or merge, keyed by resource field key.

The identifier is added to a newly inserted record automatically. If data also contains idField, use the same value as idValue.

Upsert by order_name​

Use order_name as the identifier when syncing return data for the order data resource:

curl -X POST https://api.flowcall.co/apis/resources/records/upsert \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "objectId": "3249970d-e728-4dad-9659-f8fd810c5e4b",
    "idField": "order_name",
    "idValue": "#ORDER-123",
    "data": {
      "return_type": "exchange",
      "return_shipment_awb": "AWB123456",
      "return_shipment_status": "in_transit"
    }
  }'

The match is exact. Keep formatting such as a leading # and letter casing consistent between calls.

Success response​

The operation field tells you whether the call inserted or updated the record:

{
  "success": true,
  "operation": "updated",
  "record": {
    "id": "<resource_record_id>",
    "objectId": "3249970d-e728-4dad-9659-f8fd810c5e4b",
    "customerId": null,
    "data": {
      "order_name": "#ORDER-123",
      "return_type": "exchange",
      "return_shipment_awb": "AWB123456",
      "return_shipment_status": "in_transit"
    },
    "updatedAt": "2026-08-07T10:05:00.000Z"
  },
  "conflicts": [],
  "conflictCount": 0
}

operation is either inserted or updated.

Duplicate identifiers​

Resource fields are not automatically unique. Keep one record per identifier value when using that field for upserts. If more than one existing record has the same idField and idValue, Flowcall returns 400 instead of choosing a record.

Error responses​

StatusExample messageCause
400objectId is requiredA required request field is missing.
400Unknown resource field "field_name"idField or a key in data is not configured on the object.
400More than one resource record matched the upsert id fieldThe identifier is duplicated in the resource.
403Invalid tokenThe Bearer token is invalid.
404Resource object not foundThe object does not exist or belongs to another account.