curl --request PATCH \
  --url https://integrations.polinate.ai/api/v1/buyers/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --header 'X-Business-Id: <x-business-id>' \
  --data '
{
  "buyer": {
    "name": "Updated Name Pty Ltd",
    "primaryEmail": "newemail@example.com"
  }
}
'

{
  "id": "<string>",
  "name": "<string>",
  "legalName": "<string>",
  "partnershipId": "<string>",
  "partnershipStatus": "PENDING",
  "itemListId": "<string>",
  "primaryEmail": "<string>",
  "primaryPhone": "<string>",
  "status": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>",
  "properties": {},
  "buyerInfo": {},
  "emails": [
    {
      "id": "<string>",
      "email": "jsmith@example.com",
      "contactName": "<string>",
      "isPrimary": true,
      "isVerified": true,
      "verifiedAt": "<string>",
      "sequence": 123
    }
  ],
  "phones": [
    {
      "id": "<string>",
      "phone": "<string>",
      "contactName": "<string>",
      "isPrimary": true,
      "isVerified": true,
      "verifiedAt": "<string>",
      "sequence": 123
    }
  ],
  "locations": [
    {
      "id": "<string>",
      "label": "<string>",
      "type": "<string>",
      "status": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postcode": "<string>",
      "country": "<string>"
    }
  ]
}

Buyers

Update a buyer (comprehensive CRUD)

Comprehensive buyer updates supporting:

Core buyer fields (name, legalName, primaryEmail, primaryPhone) - phantom buyers only
Partnership status updates (if supplier owns the partnership)
Create, update, and delete operations for emails, phones, and locations
Business buyers can only update partnership status (if owned)

Partnership Ownership: Only the supplier that owns the partnership can update its status. Ownership is determined by which business created the partnership.

Phantom vs Business Buyers: Phantom buyers (created via POST /buyers) support full CRUD operations. Business buyers (existing businesses) only support partnership status updates.

PATCH

/

api

/

v1

/

buyers

/

{id}

curl --request PATCH \
  --url https://integrations.polinate.ai/api/v1/buyers/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --header 'X-Business-Id: <x-business-id>' \
  --data '
{
  "buyer": {
    "name": "Updated Name Pty Ltd",
    "primaryEmail": "newemail@example.com"
  }
}
'

{
  "id": "<string>",
  "name": "<string>",
  "legalName": "<string>",
  "partnershipId": "<string>",
  "partnershipStatus": "PENDING",
  "itemListId": "<string>",
  "primaryEmail": "<string>",
  "primaryPhone": "<string>",
  "status": "<string>",
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "deletedAt": "<string>",
  "properties": {},
  "buyerInfo": {},
  "emails": [
    {
      "id": "<string>",
      "email": "jsmith@example.com",
      "contactName": "<string>",
      "isPrimary": true,
      "isVerified": true,
      "verifiedAt": "<string>",
      "sequence": 123
    }
  ],
  "phones": [
    {
      "id": "<string>",
      "phone": "<string>",
      "contactName": "<string>",
      "isPrimary": true,
      "isVerified": true,
      "verifiedAt": "<string>",
      "sequence": 123
    }
  ],
  "locations": [
    {
      "id": "<string>",
      "label": "<string>",
      "type": "<string>",
      "status": "<string>",
      "addressLine1": "<string>",
      "addressLine2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "postcode": "<string>",
      "country": "<string>"
    }
  ]
}

Headers

X-Business-Id

string

required

Business identifier for external auth. Find in Polinate app → Business Settings → Integrations.

Example:

"{{businessId}}"

X-API-Key

string

required

Per-business API key for external auth. Find in Polinate app → Business Settings → Integrations.

Example:

"{{apiKey}}"

Idempotency-Key

string

Idempotency key for POST operations

Example:

"{{idempotencyKey}}"

Path Parameters

id

string

required

Example:

"phm_123"

Body

application/json

buyer

object

Show child attributes

partnershipStatus

enum<string>

Available options:

DECLINED,

PENDING,

REVIEW,

ACTIVE,

PAUSED,

SUSPENDED,

EXPIRED,

TERMINATED

createPhones

object[]

Show child attributes

updatePhones

object[]

Show child attributes

deletePhones

string[]

createEmails

object[]

Show child attributes

updateEmails

object[]

Show child attributes

deleteEmails

string[]

createLocations

object[]

Show child attributes

updateLocations

object[]

Show child attributes

deleteLocations

string[]

Response

OK - Returns full updated buyer with all contacts

id

string

required

name

string

required

legalName

string

required

partnershipId

string

required

partnershipStatus

enum<string>

required

Available options:

PENDING,

ACTIVE,

PAUSED,

TERMINATED,

DECLINED,

EXPIRED

itemListId

string | null

required

primaryEmail

string | null

primaryPhone

string | null

status

string

createdAt

string

updatedAt

string

deletedAt

string | null

properties

object

buyerInfo

object

emails

object[]

Show child attributes

phones

object[]

Show child attributes

locations

object[]

Show child attributes