Customers API

Customers API

GET /api/integrations/v2/{connection_id}/customers

The customers this integration has linked, ids only, keyset-paged on (updated_at, external_id).

Parameters

Name	In	Type	Required	Description
connection_id	path	string (uuid)	yes	Your custom integration’s id; the connection whose secret signs the request.
updated_since	query	string (date-time), nullable	no	Only rows changed at or after this instant (inclusive).
cursor	query	string, nullable	no	The next_cursor of the previous page, as given.
limit	query	integer	no	Page size; at most 250 rows are answered whatever is asked. Default 50.

Headers

Header	Required	Description
X-Yedran-Timestamp	yes	Unix seconds; within five minutes of the server’s clock.
X-Yedran-Signature	yes	Lowercase hex HMAC-SHA256, keyed with the integration’s API secret, over METHOD\npath\ntimestamp\nsha256_hex(body).
Yedran-Version	no	Optional: the contract version, 2026-10 today; absent is 2026-10. Any other value is 400 unsupported_version. Every answer echoes the version served.

Response 200

Schema CustomerPageV2.

Field	Type	Required	Description
data	array of CustomerV2	yes
next_cursor	string, nullable	yes

Example

curl -X GET "https://app.yedran.com/api/integrations/v2/{connection_id}/customers?limit=1" \
  -H "X-Yedran-Timestamp: $TIMESTAMP" \
  -H "X-Yedran-Signature: $SIGNATURE" \
  -H "Yedran-Version: 2026-10"

Response 200:

{
  "data": [
    {
      "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
      "external_id": "string",
      "matched_by": "string",
      "linked_at": "2026-10-02T09:00:00Z",
      "updated_at": "2026-10-02T09:00:00Z"
    }
  ],
  "next_cursor": "string"
}

Errors

Code	Meaning
400	Bad Request
401	Unauthorized
422	Unprocessable Entity

GET /api/integrations/v2/{connection_id}/customers/{customer_id}

One of our customers, as this integration has linked them — 404 when it has not.

Parameters

Name	In	Type	Required	Description
connection_id	path	string (uuid)	yes	Your custom integration’s id; the connection whose secret signs the request.
customer_id	path	string (uuid)	yes

Headers

Header	Required	Description
X-Yedran-Timestamp	yes	Unix seconds; within five minutes of the server’s clock.
X-Yedran-Signature	yes	Lowercase hex HMAC-SHA256, keyed with the integration’s API secret, over METHOD\npath\ntimestamp\nsha256_hex(body).
Yedran-Version	no	Optional: the contract version, 2026-10 today; absent is 2026-10. Any other value is 400 unsupported_version. Every answer echoes the version served.

Response 200

Schema CustomerV2.

Field	Type	Required	Description
id	string (uuid)	yes
external_id	string	yes
matched_by	string, nullable	yes
linked_at	string (date-time)	yes
updated_at	string (date-time)	yes

Example

curl -X GET "https://app.yedran.com/api/integrations/v2/{connection_id}/customers/3f2504e0-4f89-11d3-9a0c-0305e82c3301" \
  -H "X-Yedran-Timestamp: $TIMESTAMP" \
  -H "X-Yedran-Signature: $SIGNATURE" \
  -H "Yedran-Version: 2026-10"

Response 200:

{
  "id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "external_id": "string",
  "matched_by": "string",
  "linked_at": "2026-10-02T09:00:00Z",
  "updated_at": "2026-10-02T09:00:00Z"
}

Errors

Code	Meaning
400	Bad Request
401	Unauthorized
404	Not Found
422	Unprocessable Entity

Schemas

CustomerPageV2

A page of the integration’s customer links, (updated_at, external_id) ascending.

Field	Type	Required	Description
data	array of CustomerV2	yes
next_cursor	string, nullable	yes

CustomerV2

One of the caller’s users, as the Yedran customer it resolves to — ids only.

The collection lists the customers THIS integration has linked (its customer.upserted, order and engagement documents), because a customer’s external_id exists only in the namespace of the integration that sent it. updated_at is when the link last changed. No archived_at.

Field	Type	Required	Description
id	string (uuid)	yes
external_id	string	yes
matched_by	string, nullable	yes
linked_at	string (date-time)	yes
updated_at	string (date-time)	yes