API documentation

Leads API

Submit a lead

Creates a lead for a physical or service product, identical to a submission from the deployed landing page checkout form. product_id must belong to the authenticated account. Required scope: leads:write.

POST/v1/accounts/{account_id}/leads

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`Idempotency-Key`	header	string	No	Optional deduplication key for POST and PATCH requests. Cached responses are replayed for 24 hours.

Request body

This request body is required.

Lead payload. Only product_id and phone are required; everything else is optional.

Field	Type	Required	Notes
`product_id`	string (uuid)	Yes	Must belong to the authenticated account.
`phone`	string	Yes	Contact phone number, ideally in E.164 format.
`first_name`	string	No
`last_name`	string	No
`email`	string (email)	No
`page_id`	string (uuid)	No	Landing page that generated this lead, if any.
`quantity`	integer	No	Default: `1`
`custom_fields`	object	No	Arbitrary extra fields, stored alongside the lead submission data.

The example below includes optional fields for context; only fields marked Yes are always required. Conditional requirements are listed in Notes.

{
  "product_id": "123e4567-e89b-42d3-a456-426614174000",
  "phone": "+21620123456",
  "first_name": "Amina",
  "last_name": "Mansour",
  "email": "amina@example.com",
  "page_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "quantity": 1,
  "custom_fields": {
    "address": "12 Rue de la Paix, Tunis"
  }
}

Response

{
  "data": {
    "id": "9b2fd0a1-4c33-4f5e-8a71-2d6e5b0c8f42",
    "lead_number": "LEAD-1752405600-037"
  }
}

cURL example

curl -X POST https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/leads \
  -H "Authorization: Bearer dmk_at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_id": "123e4567-e89b-42d3-a456-426614174000",
  "phone": "+21620123456",
  "first_name": "Amina",
  "last_name": "Mansour",
  "email": "amina@example.com",
  "page_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "quantity": 1,
  "custom_fields": {
    "address": "12 Rue de la Paix, Tunis"
  }
}'

List leads

Returns the authenticated account's leads with cursor pagination, filters, inline line items, and normalized shipping fields. Masked leads have phone_number: null and shipping: null. Required scope: leads:read.

GET/v1/accounts/{account_id}/leads

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`status`	query	string	No
`product_id`	query	string	No
`phone`	query	string	No	Substring search on phone number.
`created_after`	query	string	No
`created_before`	query	string	No
`cursor`	query	string	No	Opaque pagination cursor returned by the previous page.
`per_page`	query	integer	No	Page size between 1 and 100.
`sort`	query	string	No

Response

{
  "data": [
    {
      "id": "9b2fd0a1-4c33-4f5e-8a71-2d6e5b0c8f42",
      "lead_number": "LEAD-1752405600-037",
      "status": "pending",
      "phone_number": "+21620123456",
      "total_amount": 149,
      "delivery_price": 8,
      "is_masked": false,
      "created_at": "2026-04-28T10:00:00.000Z",
      "shipping": {
        "full_name": "Amina Mansour",
        "phone": "+21620123456",
        "email": "amina@example.com",
        "address_line": "12 Rue de la Paix",
        "city": "Tunis",
        "governorate": "Tunis",
        "postal_code": "1000",
        "country": "Tunisia",
        "notes": null
      },
      "items": [
        {
          "product_id": "123e4567-e89b-42d3-a456-426614174000",
          "product_title": "Atlas Resistance Band Kit",
          "product_price": 149,
          "quantity": 1
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

cURL example

curl -X GET https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/leads \
  -H "Authorization: Bearer dmk_at_live_xxx"

Get a lead

Returns full lead details including submission data, normalized shipping fields, seller-specific notes, and payment method. Masked leads return submission_data: null and shipping: null. Required scope: leads:read.

GET/v1/accounts/{account_id}/leads/{id}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Lead identifier.

Response

{
  "data": {
    "id": "9b2fd0a1-4c33-4f5e-8a71-2d6e5b0c8f42",
    "lead_number": "LEAD-1752405600-037",
    "status": "pending",
    "phone_number": "+21620123456",
    "total_amount": 149,
    "delivery_price": 8,
    "is_masked": false,
    "created_at": "2026-04-28T10:00:00.000Z",
    "updated_at": "2026-04-28T10:00:00.000Z",
    "shipping": {
      "full_name": "Amina Mansour",
      "phone": "+21620123456",
      "email": "amina@example.com",
      "address_line": "12 Rue de la Paix",
      "city": "Tunis",
      "governorate": "Tunis",
      "postal_code": "1000",
      "country": "Tunisia",
      "notes": null
    },
    "items": [
      {
        "product_id": "123e4567-e89b-42d3-a456-426614174000",
        "product_title": "Atlas Resistance Band Kit",
        "product_price": 149,
        "quantity": 1
      }
    ],
    "submission_data": {
      "first_name": "Amina",
      "last_name": "Mansour",
      "email": "amina@example.com",
      "address": "12 Rue de la Paix, Tunis"
    },
    "notes": null
  }
}

cURL example

curl -X GET https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/leads/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx"

Update a lead status

Changes a seller-owned lead between operational statuses and emits lead.status.changed when the value changes. System-managed abandoned, test, and duplicated statuses cannot be changed here. Repeating the current status is a no-op. Required scope: leads:write.

PATCH/v1/accounts/{account_id}/leads/{id}

Authentication

Requires bearer authentication.

Parameters

Name	In	Type	Required	Description
`account_id`	path	string	Yes	Opaque external account identifier.
`id`	path	string	Yes	Resource UUID.

Request body

This request body is required.

New operational lead status.

Field	Type	Required	Notes
`status`	string	Yes	Allowed: pending, confirmed, processing, shipped, delivered, cancelled

The example below includes optional fields for context; only fields marked Yes are always required. Conditional requirements are listed in Notes.

{
  "status": "confirmed"
}

Response

{
  "data": {
    "id": "9b2fd0a1-4c33-4f5e-8a71-2d6e5b0c8f42",
    "status": "confirmed",
    "previous_status": "pending",
    "current_status": "confirmed",
    "changed": true,
    "version": 2
  }
}

cURL example

curl -X PATCH https://api.demarky.ai/v1/accounts/acct_0123456789abcdefghjkmnpqrs/leads/f62fba7d-5af6-4741-b94b-6c362d3317af \
  -H "Authorization: Bearer dmk_at_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "confirmed"
}'