API reference

Clients

The businesses you request access from. Store your own ID on each client as externalClientId to find it again without keeping ours.

Create a client

POST /clients

Creates a client. Set externalClientId to your own ID for the client so you can find it again with GET /clients?externalClientId=; it is unique within your agency and cannot be changed once set. Emails are not unique: creating a client with an existing email makes another client.

Scope clients:create Requires Idempotency-Key

Headers

Idempotency-Key string required

A unique value per create, such as a UUID (1-255 visible ASCII characters). Retrying with the same key and body returns the original result instead of creating another object; keys are kept for 24 hours.

Body

name string required

The contact person's name. Up to 200 characters.
email string required

Up to 320 characters.
company string | null

Blank becomes null. Up to 200 characters.
website string | null

Blank becomes null. Not checked as a URL. Up to 2048 characters.
language string

The language of the client's pages and emails. One of English, Spanish, Dutch. Default "English".
metadata object

Up to 50 string values (keys up to 100 characters).
externalClientId string

Your ID for the client: unique within your agency, case-sensitive, no surrounding spaces. Cannot be changed once set. Up to 255 characters.

Returns

201 The new client.

Fields (object)

id uuid required
externalClientId string | null required

Your ID for the client, unique within your agency.
name string required

The contact person's name.
email string required
company string | null required
website string | null required
language string required

The language of the client's pages and emails. One of English, Spanish, Dutch.
metadata object required

Your own string values.
createdAt datetime required

400 The request is invalid (VALIDATION_FAILED); details lists the problems, with field when one applies.
401 The API key is missing, invalid or revoked.
403 The key lacks the scope (CAPABILITY_REQUIRED), the plan has no API access (PLAN_NOT_ENTITLED), or, when creating a request, the monthly limit is reached (PLAN_LIMIT_REACHED).
409 A conflict: an externalClientId in use or immutable, an Idempotency-Key reused with a different body or still in progress, or a request in a state that does not allow this.
429 Rate limited (RATE_LIMITED); wait for Retry-After seconds.

Request

curl -X POST "https://api.agencyaccess.co/api/v2/clients" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "name": "Jamie Rivera",
  "email": "jamie@northwindcoffee.com",
  "company": "Northwind Coffee",
  "website": "https://northwindcoffee.com",
  "externalClientId": "crm-4821",
  "metadata": {
    "accountManager": "Priya"
  }
}
JSON

const res = await fetch("https://api.agencyaccess.co/api/v2/clients", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AGENCYACCESS_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Jamie Rivera",
    "email": "jamie@northwindcoffee.com",
    "company": "Northwind Coffee",
    "website": "https://northwindcoffee.com",
    "externalClientId": "crm-4821",
    "metadata": {
      "accountManager": "Priya"
    }
  }),
})
const { data } = await res.json()

Response 201

{
  "data": {
    "id": "7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17",
    "externalClientId": "crm-4821",
    "name": "Jamie Rivera",
    "email": "jamie@northwindcoffee.com",
    "company": "Northwind Coffee",
    "website": "https://northwindcoffee.com",
    "language": "English",
    "metadata": {
      "accountManager": "Priya"
    },
    "createdAt": "2026-10-07T09:12:44.000Z"
  },
  "meta": {
    "requestId": "req_1f0b6c2e9a7d4f58b3c1e6a9d2f4b7c0"
  }
}

List clients

GET /clients

Lists all your clients and prospects, including those created in the dashboard and on access pages, oldest first. Filter by externalClientId to find one client by your own ID, or by email (several clients can share an email).

Scope clients:read

Query parameters

limit integer

Results per page, 1-100.
cursor string

The meta.nextCursor of the previous page. Cursors only work with the filters they were issued for.
externalClientId string

Only the client with this external ID (case-sensitive).
email string

Only clients with this email (case-insensitive).

Returns

200 A page of clients.

Fields of each item (object)

id uuid required
externalClientId string | null required

Your ID for the client, unique within your agency.
name string required

The contact person's name.
email string required
company string | null required
website string | null required
language string required

The language of the client's pages and emails. One of English, Spanish, Dutch.
metadata object required

Your own string values.
createdAt datetime required

400 The request is invalid (VALIDATION_FAILED); details lists the problems, with field when one applies.
401 The API key is missing, invalid or revoked.
403 The key lacks the scope (CAPABILITY_REQUIRED), the plan has no API access (PLAN_NOT_ENTITLED), or, when creating a request, the monthly limit is reached (PLAN_LIMIT_REACHED).
429 Rate limited (RATE_LIMITED); wait for Retry-After seconds.

Request

curl "https://api.agencyaccess.co/api/v2/clients?externalClientId=crm-4821" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY"

const res = await fetch("https://api.agencyaccess.co/api/v2/clients?externalClientId=crm-4821", {
  headers: {
    Authorization: `Bearer ${process.env.AGENCYACCESS_API_KEY}`,
  },
})
const { data, meta } = await res.json()
// meta.nextCursor: pass as ?cursor= for the next page

Response 200

{
  "data": [
    {
      "id": "7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17",
      "externalClientId": "crm-4821",
      "name": "Jamie Rivera",
      "email": "jamie@northwindcoffee.com",
      "company": "Northwind Coffee",
      "website": "https://northwindcoffee.com",
      "language": "English",
      "metadata": {
        "accountManager": "Priya"
      },
      "createdAt": "2026-10-07T09:12:44.000Z"
    }
  ],
  "meta": {
    "requestId": "req_1f0b6c2e9a7d4f58b3c1e6a9d2f4b7c0",
    "nextCursor": null
  }
}

Retrieve a client

GET /clients/{id}

Scope clients:read

Path parameters

id uuid required

The client ID.

Returns

200 The client.

Fields (object)

id uuid required
externalClientId string | null required

Your ID for the client, unique within your agency.
name string required

The contact person's name.
email string required
company string | null required
website string | null required
language string required

The language of the client's pages and emails. One of English, Spanish, Dutch.
metadata object required

Your own string values.
createdAt datetime required

401 The API key is missing, invalid or revoked.
403 The key lacks the scope (CAPABILITY_REQUIRED), the plan has no API access (PLAN_NOT_ENTITLED), or, when creating a request, the monthly limit is reached (PLAN_LIMIT_REACHED).
404 Not found, or it belongs to another agency.
429 Rate limited (RATE_LIMITED); wait for Retry-After seconds.

Request

curl "https://api.agencyaccess.co/api/v2/clients/7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY"

const res = await fetch("https://api.agencyaccess.co/api/v2/clients/7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17", {
  headers: {
    Authorization: `Bearer ${process.env.AGENCYACCESS_API_KEY}`,
  },
})
const { data } = await res.json()

Response 200

{
  "data": {
    "id": "7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17",
    "externalClientId": "crm-4821",
    "name": "Jamie Rivera",
    "email": "jamie@northwindcoffee.com",
    "company": "Northwind Coffee",
    "website": "https://northwindcoffee.com",
    "language": "English",
    "metadata": {
      "accountManager": "Priya"
    },
    "createdAt": "2026-10-07T09:12:44.000Z"
  },
  "meta": {
    "requestId": "req_1f0b6c2e9a7d4f58b3c1e6a9d2f4b7c0"
  }
}

Update a client

PATCH /clients/{id}

Changes the fields you send. externalClientId can be set on a client that has none; changing an existing one returns 409 EXTERNAL_CLIENT_ID_IMMUTABLE. Send null or an empty string to clear company or website.

Scope clients:update

Path parameters

id uuid required

The client ID.

Body

Send only the fields to change.

name string

Up to 200 characters.
email string

Up to 320 characters.
company string | null

Up to 200 characters.
website string | null

Up to 2048 characters.
language string

The language of the client's pages and emails. One of English, Spanish, Dutch.
metadata object

Replaces all metadata.
externalClientId string

Only when the client has none yet. Up to 255 characters.

Returns

200 The updated client.

Fields (object)

id uuid required
externalClientId string | null required

Your ID for the client, unique within your agency.
name string required

The contact person's name.
email string required
company string | null required
website string | null required
language string required

The language of the client's pages and emails. One of English, Spanish, Dutch.
metadata object required

Your own string values.
createdAt datetime required

400 The request is invalid (VALIDATION_FAILED); details lists the problems, with field when one applies.
401 The API key is missing, invalid or revoked.
403 The key lacks the scope (CAPABILITY_REQUIRED), the plan has no API access (PLAN_NOT_ENTITLED), or, when creating a request, the monthly limit is reached (PLAN_LIMIT_REACHED).
404 Not found, or it belongs to another agency.
409 A conflict: an externalClientId in use or immutable, an Idempotency-Key reused with a different body or still in progress, or a request in a state that does not allow this.
429 Rate limited (RATE_LIMITED); wait for Retry-After seconds.

Request

curl -X PATCH "https://api.agencyaccess.co/api/v2/clients/7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17" \
  -H "Authorization: Bearer $AGENCYACCESS_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "company": "Northwind Coffee Roasters",
  "metadata": {
    "accountManager": "Sam"
  }
}
JSON

const res = await fetch("https://api.agencyaccess.co/api/v2/clients/7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.AGENCYACCESS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "company": "Northwind Coffee Roasters",
    "metadata": {
      "accountManager": "Sam"
    }
  }),
})
const { data } = await res.json()

Response 200

{
  "data": {
    "id": "7c1e9f52-3b8a-4d2e-9a61-5f0c2d8b4e17",
    "externalClientId": "crm-4821",
    "name": "Jamie Rivera",
    "email": "jamie@northwindcoffee.com",
    "company": "Northwind Coffee Roasters",
    "website": "https://northwindcoffee.com",
    "language": "English",
    "metadata": {
      "accountManager": "Sam"
    },
    "createdAt": "2026-10-07T09:12:44.000Z"
  },
  "meta": {
    "requestId": "req_1f0b6c2e9a7d4f58b3c1e6a9d2f4b7c0"
  }
}