Customers

Customer management endpoints

List customers

get

Retrieve a paginated list of customers

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Query parameters

pageintegerOptional

Page number

Example: 1

per_pageinteger · max: 100Optional

Items per page (max 100)

Example: 25

includestringOptional

Comma-separated list of expansions: cards, fields, stats, integrations, subscriptions

Example: cards,fields

searchstringOptional

Search across: name_first, name_last, email

Example: search term

filter[id]stringOptional

Filter by id (exact match)

filter[id.gte]stringOptional

Filter by id (greater than or equal)

filter[id.lte]stringOptional

Filter by id (less than or equal)

filter[email]stringOptional

Filter by email (exact match)

filter[email.contains]stringOptional

Filter by email (contains)

filter[name_first]stringOptional

Filter by name_first (exact match)

filter[name_first.contains]stringOptional

Filter by name_first (contains)

filter[name_last]stringOptional

Filter by name_last (exact match)

filter[name_last.contains]stringOptional

Filter by name_last (contains)

filter[company_name]stringOptional

Filter by company_name (exact match)

filter[company_name.contains]stringOptional

Filter by company_name (contains)

filter[created_at]stringOptional

Filter by created_at (exact match)

filter[updated_at]stringOptional

Filter by updated_at (exact match)

sortstringOptional

Sort field (prefix with - for descending)

Example: -created_at

Responses

200

Successful response with paginated list

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

get

/v2/customers/

HTTPcURLJavaScriptPython

GET /v2/customers/ HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 150,
    "pages": 6
  }
}

Update customer fields

patch

Update customer core and custom fields. Accepts an array of field objects.

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Body

application/json

Responses

200

Successful response

application/json

anyOptional

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

409

Conflict - The request conflicts with the current state of the resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

patch

/v2/customers/{id}

HTTPcURLJavaScriptPython

PATCH /v2/customers/{id} HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "fields": [
    {
      "field_id": "text",
      "field_name": "text",
      "field_type": "text",
      "value": null
    }
  ]
}

No content

Add note to customer

post

Add a note to customer activity history

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Body

application/json

notesstring · min: 1Required

Responses

201

Created successfully

application/json

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

409

Conflict - The request conflicts with the current state of the resource

application/json

500

Internal Server Error - An unexpected error occurred

application/json

post

/v2/customers/{id}/notes

HTTPcURLJavaScriptPython

POST /v2/customers/{id}/notes HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 16

{
  "notes": "text"
}

No content

Preview customer merge

get

Preview the result of merging secondary customer into primary customer. Returns both customers and potential conflicts.

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Path parameters

primary_idstringRequired

Primary customer ID (will remain after merge)

secondary_idstringRequired

Secondary customer ID (will be deleted after merge)

Responses

200

Successful response

application/json

anyOptional

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

404

Not Found - The requested resource does not exist

application/json

500

Internal Server Error - An unexpected error occurred

application/json

get

/v2/customers/{primary_id}/merge/{secondary_id}

HTTPcURLJavaScriptPython

GET /v2/customers/{primary_id}/merge/{secondary_id} HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Merge customers

post

Merge secondary customer into primary customer. All orders, cards, and data from secondary customer will be transferred to primary customer. Secondary customer will be deleted.

Authorizations

ApiKeyAuthOAuth2

AuthorizationstringRequired

Account API key authentication. Pass your API key as a Bearer token in the Authorization header. Grants full access to all endpoints — equivalent to all OAuth scopes.

Path parameters

primary_idstringRequired

Primary customer ID (will remain after merge)

secondary_idstringRequired

Secondary customer ID (will be deleted after merge)

Body

application/json

Responses

200

Successful response

application/json

anyOptional

400

Bad Request - The request was invalid or malformed

application/json

401

Unauthorized - Authentication is required or has failed

application/json

403

Forbidden - You do not have permission to access this resource

application/json

404

Not Found - The requested resource does not exist

application/json

500

Internal Server Error - An unexpected error occurred

application/json

post

/v2/customers/{primary_id}/merge/{secondary_id}

HTTPcURLJavaScriptPython

POST /v2/customers/{primary_id}/merge/{secondary_id} HTTP/1.1
Host: api.spiffy.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "fields": [
    {
      "field_id": "text",
      "use_primary": true
    }
  ]
}

No content