# Bulk create or update contacts

Source: https://joinsimplesms.com/docs/api/contacts/import
Index: https://joinsimplesms.com/llms.txt

`POST /v1/contacts/import`

Up to 500 per request, keyed on phone number, with the same merge rule as POST /contacts. Rows that cannot be imported come back in skipped; the rest still land. `dry_run: true` returns the summary (found, valid, malformed, duplicates, landlines, already opted out, will create / update, eligible) and writes nothing. A row with `opt_in.status: true` (or a date or source) stores opt-in evidence in the consent ledger; `opt_in.status: false` records the number as opted out. An import never opts anyone back in.

Send your API key as a bearer token: `Authorization: Bearer ssms_sk_...`. Test keys run this endpoint against the [sandbox](/docs/sandbox); see [Authentication](/docs/authentication) for key modes and scopes.

## Request body

JSON (`Content-Type: application/json`).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `contacts` | array of ContactInput | Yes | At most 500 items. |
| `dry_run` | boolean | No |  |
| `check_line_types` | boolean | No | dry_run only. Looks up line types to count landlines; live lookups are paid, so only the first 500 numbers are checked. |
| `import_id` | string | No | From a previous response, to group several requests as one import. |
| `name` | string | No | A label for the import (first request only). |

## Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Import result, or the dry-run preview | JSON object |
| 400 | Invalid request | `Error` |
| 401 | Missing, malformed, or revoked API key | `Error` |
| 402 | Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged | `Error` |
| 429 | Rate limit or quota exceeded | `Error` |

### 200: response fields

| Field | Type | Description |
| --- | --- | --- |
| `object` | `contact_import`, `contact_import_preview` |  |
| `created` | integer |  |
| `updated` | integer |  |
| `skipped` | array of object |  |
| `skipped[].index` | integer | Position of the row in the request |
| `skipped[].value` | string |  |
| `skipped[].reason` | string |  |
| `import_id` | string | Example: `imp_a1B2c3D4e5`. |
| `opted_out` | integer | Rows recorded as opted out because they were marked unsubscribed. |
| `summary` | object | dry_run only. |
| `summary.found` | integer |  |
| `summary.valid` | integer |  |
| `summary.malformed` | integer |  |
| `summary.duplicates` | integer |  |
| `summary.landlines` | integer | null unless check_line_types was set Nullable. |
| `summary.already_opted_out` | integer |  |
| `summary.marked_unsubscribed` | integer |  |
| `summary.will_create` | integer |  |
| `summary.will_update` | integer |  |
| `summary.eligible` | integer | Would receive a broadcast today |
| `rejected` | array of object | dry_run only. |
| `rejected[].index` | integer |  |
| `rejected[].phone_number` | string |  |
| `rejected[].reason` | `malformed`, `duplicate`, `landline` |  |
| `rejected[].detail` | string |  |

## Errors

| Status | When |
| --- | --- |
| 400 | Invalid request |
| 401 | Missing, malformed, or revoked API key |
| 402 | Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged |
| 429 | Rate limit or quota exceeded |

Every error has the same JSON shape, and `request_id` matches the `X-Request-Id` response header. [Errors](/docs/errors) lists every code and what to do about it.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "What went wrong, in plain words.",
    "param": "the_field",
    "request_id": "req_a1B2c3D4e5F6g7H8"
  }
}
```

## Examples

### curl

```bash
curl -X POST "https://api.joinsimplesms.com/v1/contacts/import" \
  -H "Authorization: Bearer $SIMPLESMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "contacts": [
    {
      "phone_number": "+14155550132"
    }
  ]
}'
```

### Node.js

```javascript
import { SimpleSMS } from 'joinsimplesms'; // npm install joinsimplesms

const sms = new SimpleSMS(process.env.SIMPLESMS_API_KEY);

const result = await sms.contacts.import([
  { phoneNumber: '+14155550132', name: 'Jane Doe', tags: ['customers'] },
  { phoneNumber: '+14155550133', name: 'Sam Lee' },
]);
```

### Python

```python
import os
from joinsimplesms import SimpleSMS  # pip install joinsimplesms

client = SimpleSMS(os.environ["SIMPLESMS_API_KEY"])

result = client.contacts.import_([
    {"phone_number": "+14155550132", "name": "Jane Doe", "tags": ["customers"]},
    {"phone_number": "+14155550133", "name": "Sam Lee"},
])
```

## Related

- Guide: [Contacts](/docs/contacts)
- [All contacts endpoints](/docs/api#contacts)
- [API reference](/docs/api)