# Nexus Contacts API

Human-readable version: https://docs.nexus-payment.com/contacts-api - machine-readable spec: https://docs.nexus-payment.com/openapi.json

The Contacts API lets your own systems (a CRM, an HR system, a sign-up form) keep your organization's contact list in Nexus up to date: add people one by one or thousands at once, look them up, and remove them.

## Getting started

1. Create a Nexus account at https://nexus-payment.com/signup and set up your organization (or log in).
2. In the dashboard open Settings > Integrations > API keys (https://dashboard.nexus-payment.com/settings/integrations/api-keys), click Create key, choose its permissions and copy it. Only owners, admins and developers can create keys. The key is shown only once.
3. Send the key on every request: `Authorization: Bearer nxk_live_YOUR_API_KEY`. The key alone identifies your organization - never send an organization id.

## Production and sandbox

|  | Address | Key |
| --- | --- | --- |
| Production (your real data) | https://api.nexus-payment.com/api/v1/integrations/contacts | `nxk_live_...` from Settings > Integrations > API keys |
| Sandbox (docs Try it out only) | https://sandbox.nexus-payment.com/api/v1/integrations/contacts | `nxk_test_sandbox_...` created by the docs page |

Real keys work only on production and sandbox keys only in the sandbox; the other combination answers `401 invalid_api_key`. The sandbox never holds real data, keeps test contacts for 24 hours and takes at most 1,000 rows per bulk call.

## API keys

- Permissions per key: `contacts:read`, `contacts:write`, `contacts:delete` (delete is off by default). Permissions cannot be changed later - create a new key.
- Optional expiry: never, 30, 90 or 365 days. Optional IP allow-list (single IPs or CIDR ranges).
- Up to 10 active keys per organization. Revoke any key in Settings > Integrations > API keys; it stops working immediately.
- Owners and admins get an email when a key is created or revoked, and a week before a key expires.
- Keep keys on your server only - never in a website, mobile app or public repository.

## Allowed services

- `"allowedServices": ["benefits_catalog"]` - the person is approved into your Nexus Wallet automatically when they ask to join; a request that is already waiting is approved right away.
- Leave `allowedServices` out (or send `[]`) - no automatic approval; their join request waits for an admin unless your organization approves everyone automatically.
- For an existing contact, services are only ever added. Removing a service never removes someone who already joined.
- `benefits_catalog` is the only service today; any other value is refused with `service_not_available`.

## Registered members

Every contact has a `status`. A person who joined your organization (their join request in the Nexus Wallet was approved, or they accepted a staff invitation) is a contact with status `active`. To get all of them, list contacts with `status=active` and follow `nextCursor` until it is `null`.

- `active` - joined your organization (a registered member). `joinedAt` is the date they joined; `createdAt` is when the contact was first added, which can be earlier.
- `inactive` - on your contact list, has not joined yet.
- `pending` - a staff invitation was sent and not accepted yet.
- `expired` - a staff invitation expired before it was accepted.
- `source` is how the contact was FIRST added and never changes. `source=join_request` = people who joined from the Nexus Wallet without being on your list first; someone you added (api, import, manual) who later joined keeps their original source.
- People who asked to join and are still waiting for approval are not contacts yet, so no list returns them.

```javascript
const BASE = 'https://api.nexus-payment.com/api/v1/integrations/contacts';
const headers = { Authorization: 'Bearer nxk_live_YOUR_API_KEY' };

const members = [];
let cursor = null;
do {
  const params = new URLSearchParams({ status: 'active', limit: '100' });
  if (cursor) params.set('cursor', cursor);
  const res = await fetch(`${BASE}?${params}`, { headers });
  if (!res.ok) throw new Error(`Nexus API ${res.status}`);
  const page = await res.json();
  members.push(...page.data);
  cursor = page.nextCursor;
} while (cursor);
```

## Contact fields

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | One of email / phone | Email address. You must send email, phone, or both. |
| `phone` | string | One of email / phone | Israeli mobile number: 05XXXXXXXX or +9725XXXXXXXX. You must send email, phone, or both. |
| `firstName` | string | No | First name (up to 100 characters). |
| `lastName` | string | No | Last name (up to 100 characters). |
| `address` | string | No | Free-text address (up to 500 characters). |
| `externalId` | string | No | Your own id for this person (for example your CRM id). Unique in your organization. Letters, digits and . _ : - only, up to 100 characters. Lets you find or delete the contact later without storing our id. |
| `allowedServices` | string[] | No | Services this person is approved for automatically. Today the only value is "benefits_catalog" (the Nexus Wallet). Leave it out to grant nothing. |
| `customFields` | object | No | Extra columns, by column name or column id (up to 50). See "Custom fields" below. |

## Endpoints

### Create a Contact

`POST /api/v1/integrations/contacts` - permission `contacts:write`

Adds one person to your organization's contacts. If the person already exists (same externalId, email or phone) nothing is duplicated - the existing contact is updated instead.

- A new contact answers 201 with result.status "created".
- An existing contact answers 200 with result.status "merged". Only EMPTY fields are filled in - we never overwrite data your team already entered, and services are only added, never removed.
- If externalId points at one contact and the email at a different one, the call fails with identifier_conflict and nothing is written.
- Sending "benefits_catalog" also approves this person's join request to your wallet if they already sent one and it is waiting.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string | One of email / phone | Email address. You must send email, phone, or both. |
| `phone` | string | One of email / phone | Israeli mobile number: 05XXXXXXXX or +9725XXXXXXXX. You must send email, phone, or both. |
| `firstName` | string | No | First name (up to 100 characters). |
| `lastName` | string | No | Last name (up to 100 characters). |
| `address` | string | No | Free-text address (up to 500 characters). |
| `externalId` | string | No | Your own id for this person (for example your CRM id). Unique in your organization. Letters, digits and . _ : - only, up to 100 characters. Lets you find or delete the contact later without storing our id. |
| `allowedServices` | string[] | No | Services this person is approved for automatically. Today the only value is "benefits_catalog" (the Nexus Wallet). Leave it out to grant nothing. |
| `customFields` | object | No | Extra columns, by column name or column id (up to 50). See "Custom fields" below. |

**Example request**

```bash
curl -X POST 'https://api.nexus-payment.com/api/v1/integrations/contacts' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "firstName": "Dana",
  "lastName": "Cohen",
  "email": "dana@example.com",
  "phone": "0521234567",
  "externalId": "crm-1001",
  "allowedServices": [
    "benefits_catalog"
  ],
  "customFields": {
    "בניין": "A3",
    "Floor": "4"
  }
}'
```

**Example response - 201 Created**

```json
{
  "result": {
    "index": 0,
    "status": "created",
    "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f"
  },
  "contact": {
    "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f",
    "externalId": "crm-1001",
    "firstName": "Dana",
    "lastName": "Cohen",
    "email": "dana@example.com",
    "phone": "0521234567",
    "address": null,
    "allowedServices": [
      "benefits_catalog"
    ],
    "customFields": {
      "בניין": "A3",
      "Floor": "4"
    },
    "customFieldIds": {
      "cf_8d1f0a2b": "A3",
      "cf_3c9e7b41": "4"
    },
    "status": "inactive",
    "source": "api",
    "joinedAt": null,
    "createdAt": "2026-10-21T09:30:00.000Z",
    "updatedAt": "2026-10-21T09:30:00.000Z"
  },
  "joinRequestsApproved": 0
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 400 | `validation_error` | A field is missing or invalid (for example no email and no phone, or a bad phone number). result.details lists what is wrong. |
| 400 | `service_not_available` | allowedServices contains a service that is not available yet. |
| 400 | `identifier_conflict` | The identifiers you sent belong to two different contacts. |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### Create Contacts in Bulk

`POST /api/v1/integrations/contacts/bulk` - permission `contacts:write`

Adds up to 10,000 contacts in one call. Every row is handled on its own - a bad row fails alone and the rest are still saved. Same merge rules as creating one contact.

- The answer has a summary (created / merged / failed) and one result per row, in the same order you sent them (index).
- Two rows in the same call with the same email, phone or externalId: the later one fails with duplicate_in_batch.
- Up to 10 bulk calls per minute per key.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `contacts` | object[] | Yes | 1 to 10,000 contacts, each with the fields of "Create a Contact". |

**Example request**

```bash
curl -X POST 'https://api.nexus-payment.com/api/v1/integrations/contacts/bulk' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "contacts": [
    {
      "firstName": "Dana",
      "email": "dana@example.com",
      "externalId": "crm-1001",
      "allowedServices": [
        "benefits_catalog"
      ]
    },
    {
      "firstName": "Avi",
      "email": "avi@example.com",
      "externalId": "crm-1002"
    }
  ]
}'
```

**Example response - 200 OK**

```json
{
  "summary": {
    "created": 2,
    "merged": 0,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "status": "created",
      "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f"
    },
    {
      "index": 1,
      "status": "created",
      "tenantContactId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
    }
  ],
  "joinRequestsApproved": 0
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 400 | (message only) | The body is not { "contacts": [...] } or has more than 10,000 rows. (Bad single rows do NOT fail the call - they show in results.) |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### Get a Contact

`GET /api/v1/integrations/contacts/{tenantContactId}` - permission `contacts:read`

Returns one contact by the Nexus id you received when you created it.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tenantContactId` | string | Yes | The contact id returned by create (contact.tenantContactId). |

**Example request**

```bash
curl -X GET 'https://api.nexus-payment.com/api/v1/integrations/contacts/6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY'
```

**Example response - 200 OK**

```json
{
  "contact": {
    "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f",
    "externalId": "crm-1001",
    "firstName": "Dana",
    "lastName": "Cohen",
    "email": "dana@example.com",
    "phone": "0521234567",
    "address": null,
    "allowedServices": [
      "benefits_catalog"
    ],
    "customFields": {
      "בניין": "A3",
      "Floor": "4"
    },
    "customFieldIds": {
      "cf_8d1f0a2b": "A3",
      "cf_3c9e7b41": "4"
    },
    "status": "inactive",
    "source": "api",
    "joinedAt": null,
    "createdAt": "2026-10-21T09:30:00.000Z",
    "updatedAt": "2026-10-21T09:30:00.000Z"
  }
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `contact_not_found` | No contact with this id in your organization. |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### Find a Contact

`GET /api/v1/integrations/contacts?externalId= | ?email= | ?phone=` - permission `contacts:read`

Finds one contact by your own externalId, by email, or by phone. Send exactly one of them.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | string | One of externalId / email / phone | Your own id, as sent on create. |
| `email` | string | One of externalId / email / phone | Email address (not case sensitive). |
| `phone` | string | One of externalId / email / phone | Israeli mobile number (05XXXXXXXX or +9725XXXXXXXX). |

**Example request**

```bash
curl -X GET 'https://api.nexus-payment.com/api/v1/integrations/contacts?email=dana@example.com' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY'
```

**Example response - 200 OK**

```json
{
  "contact": {
    "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f",
    "externalId": "crm-1001",
    "firstName": "Dana",
    "lastName": "Cohen",
    "email": "dana@example.com",
    "phone": "0521234567",
    "address": null,
    "allowedServices": [
      "benefits_catalog"
    ],
    "customFields": {
      "בניין": "A3",
      "Floor": "4"
    },
    "customFieldIds": {
      "cf_8d1f0a2b": "A3",
      "cf_3c9e7b41": "4"
    },
    "status": "inactive",
    "source": "api",
    "joinedAt": null,
    "createdAt": "2026-10-21T09:30:00.000Z",
    "updatedAt": "2026-10-21T09:30:00.000Z"
  }
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 404 | `contact_not_found` | No contact matches. |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### List Contacts

`GET /api/v1/integrations/contacts?limit=&cursor=&status=&source=` - permission `contacts:read`

Lists your organization's contacts, newest first, a page at a time. Add status=active to get only the people who joined your organization (your registered members).

- To get the next page, send the nextCursor value you received. nextCursor is null on the last page.
- Keep the same status / source on every page of one listing - the cursor continues the same filtered list.
- status=active returns only registered members. See "Registered members" above for what each status means.
- joinedAt on each contact is when the person joined your organization (null if they have not joined). createdAt is when the contact was first added, which can be earlier.
- status and source work only for listing. Do not send them together with externalId, email or phone (400).
- In the Try it out sandbox nobody joins, so every test contact is status inactive / source api - status=active returns an empty list there.

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | number | No | Contacts per page, 1 to 100. Default 25. |
| `cursor` | string | No | The nextCursor from the previous page. Leave it out for the first page. |
| `status` | string | No | Only contacts with this status: active (joined your organization), inactive (on your list, not joined yet), pending (staff invitation sent) or expired (staff invitation expired). |
| `source` | string | No | Only contacts FIRST added this way (it never changes when they later join): manual, import, api, gift, join_request (joined from the Nexus Wallet without being on your list first), join_gift, staff_invite or member_email_change. |

**Example request**

```bash
curl -X GET 'https://api.nexus-payment.com/api/v1/integrations/contacts?status=active&limit=25' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY'
```

**Example response - 200 OK**

```json
{
  "data": [
    {
      "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f",
      "externalId": "crm-1001",
      "firstName": "Dana",
      "lastName": "Cohen",
      "email": "dana@example.com",
      "phone": "0521234567",
      "address": null,
      "allowedServices": [
        "benefits_catalog"
      ],
      "customFields": {
        "בניין": "A3",
        "Floor": "4"
      },
      "customFieldIds": {
        "cf_8d1f0a2b": "A3",
        "cf_3c9e7b41": "4"
      },
      "status": "active",
      "source": "api",
      "joinedAt": "2026-10-25T14:12:00.000Z",
      "createdAt": "2026-10-21T09:30:00.000Z",
      "updatedAt": "2026-10-21T09:30:00.000Z"
    }
  ],
  "nextCursor": "MTc5MjU3ODQ0Mzg0OS42YWQ4YTcxZjI2OWZmZGY3ZmE4ZTdkOWM"
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_cursor` | The cursor is not one we gave you. |
| 400 | (message only) | status or source has an unknown value, or was sent together with externalId, email or phone. |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### Delete a Contact

`DELETE /api/v1/integrations/contacts/{tenantContactId}  or  ?externalId=` - permission `contacts:delete`

Deletes one contact, by the Nexus id or by your externalId. Deleting is permanent.

- Only contacts who have NOT joined your organization yet can be deleted. People who already joined are members - remove them from the dashboard instead.
- Contacts with a pending staff invitation are not deleted either.
- To delete by email or phone: first find the contact, then delete it by its tenantContactId.

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tenantContactId` | string | One of tenantContactId / externalId | The contact id (or send ?externalId= instead). |

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `externalId` | string | One of tenantContactId / externalId | Your own id, as sent on create (instead of the path id). |

**Example request**

```bash
curl -X DELETE 'https://api.nexus-payment.com/api/v1/integrations/contacts/6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY'
```

**Example response - 200 OK**

```json
{
  "result": {
    "index": 0,
    "status": "deleted",
    "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f"
  }
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 409 | `skipped_active` | The person already joined your organization (a member). Not deleted. |
| 409 | `skipped_invited` | The contact has a pending staff invitation. Not deleted. |
| 404 | `contact_not_found` | No contact with this id / externalId. |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### Delete Contacts in Bulk

`POST /api/v1/integrations/contacts/bulk-delete` - permission `contacts:delete`

Deletes up to 10,000 contacts in one call, each by tenantContactId or externalId. Same rules as deleting one.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | object[] | Yes | 1 to 10,000 items, each { "tenantContactId": "..." } or { "externalId": "..." }. |

**Example request**

```bash
curl -X POST 'https://api.nexus-payment.com/api/v1/integrations/contacts/bulk-delete' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "items": [
    {
      "externalId": "crm-1001"
    },
    {
      "tenantContactId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
    }
  ]
}'
```

**Example response - 200 OK**

```json
{
  "summary": {
    "deleted": 1,
    "skipped": 1,
    "notFound": 0,
    "failed": 0
  },
  "results": [
    {
      "index": 0,
      "status": "deleted",
      "tenantContactId": "6f1c2d3e-4b5a-4c7d-9e8f-0a1b2c3d4e5f"
    },
    {
      "index": 1,
      "status": "skipped_active",
      "tenantContactId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
    }
  ]
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 400 | (message only) | The body is not { "items": [...] } or has more than 10,000 items. |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

### Delete All Contacts of This Key

`POST /api/v1/integrations/contacts/delete-all` - permission `contacts:delete`

Deletes every contact that THIS API key created and that has not joined your organization. Contacts added in the dashboard, by file import, or by other keys are never touched. Handy before a full re-sync.

- Run it first with "dryRun": true - you get the count and nothing is deleted.
- The body must contain "confirm": "DELETE_ALL_CONTACTS", so it can never run by accident.
- Your organization's owners and admins get an email after a real (not dry-run) delete-all.

**Request body**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string | Yes | Must be exactly "DELETE_ALL_CONTACTS". |
| `dryRun` | boolean | No | true = only count, delete nothing. Default false. |

**Example request**

```bash
curl -X POST 'https://api.nexus-payment.com/api/v1/integrations/contacts/delete-all' \
  -H 'Authorization: Bearer nxk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
  "confirm": "DELETE_ALL_CONTACTS",
  "dryRun": true
}'
```

**Example response - 200 OK**

```json
{
  "dryRun": true,
  "matched": 42,
  "deleted": 0
}
```

**Errors**

| Status | Code | When |
| --- | --- | --- |
| 400 | (message only) | confirm is missing or not exactly "DELETE_ALL_CONTACTS". |
| 401 | `missing_api_key` | No key was sent - add the header Authorization: Bearer <your key>. |
| 401 | `invalid_api_key` | A key was sent but it is wrong, revoked or expired (or it is a sandbox key sent to production, or the other way round). |
| 403 | `insufficient_scope` | The key does not have the permission this call needs. |
| 403 | `ip_not_allowed` | The key has an IP allow-list and the call came from another address. |
| 429 | `rate_limited` | Too many calls - wait a minute and retry. |

## Custom fields

- Send them in `customFields` as `{ "column": "value" }`, by column name (Hebrew works; spacing and upper/lower case do not matter) or by column id (`cf_...`, never changes on rename - see Settings > Integrations > API keys or `customFieldIds` in responses).
- A name that does not exist yet creates a text column automatically (25 columns per organization).
- Values must fit the column type; on an existing contact only empty columns are filled.
- A field that could not be saved never fails the contact: it is listed in `result.skippedFields` with a reason: `custom_field_limit_reached`, `unknown_custom_field`, `invalid_value` or `read_only_field`.

## Hebrew

Send the body as UTF-8 with `Content-Type: application/json; charset=utf-8` - every common language and tool does this. Do not paste Hebrew into a Windows terminal (PowerShell / Command Prompt): it can reverse the text before it is sent. From a terminal, write Hebrew as JSON escapes, e.g. `בניין` = `\u05d1\u05e0\u05d9\u05d9\u05df`.

## Limits

- 120 calls per minute per key, of which up to 10 bulk calls (bulk create, bulk delete, delete all); over the limit: `429 rate_limited`.
- 10,000 rows per bulk create / bulk delete call; 100 contacts per page when listing.
- 25 custom columns per organization, 50 custom fields per contact per call.
- Every contact needs an email or an Israeli mobile number (or both).
