> For the complete documentation index, see [llms.txt](https://docs.genlogs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.genlogs.io/carrier/onboarded-carriers/create-onboarded-carriers-bulk.md).

# Create Onboarded Carriers Bulk

Create multiple onboarded carrier contacts in one request. Valid contacts are created and invalid ones are returned with their error.

### **Authentication**

* Include your **`Access-Token`** in the header of your requests.
* Include your **`x-api-key`** The API key provided by GenLogs. This header must be included in the request.

### Permissions

The `external-api-create-onboarded-carrier-contact` permission is required to access this endpoint.

### **Endpoint**

* **URL:** `https://api.genlogs.io/onboarded-carrier/bulk/contacts`
* **Method:** `POST`

### **Headers**

* **Access-Token** (string, required): Access token obtained from the "Create Access Token" endpoint.
* **x-api-key** (string, required): The API key provided by GenLogs.
* **Content-Type** (string, required): `application/json`.

### Request body

* **contacts** (array of objects, required): Contacts to create. Must contain between 1 and 500 items. Each item accepts:
  * **usdot** (string, required): Carrier USDOT number. Must contain digits only, be greater than zero, and be at most 9 digits. Leading zeros are removed before saving.
  * **name** (string, optional): Contact name. Letters, numbers, and spaces only.
  * **phone** (string, optional): Contact phone number. Digits only, with an optional leading `+`. Spaces, dashes, and parentheses are removed before validation.
  * **email** (string, optional): Contact email address. Must be a valid email address.

#### **Validation rules**

* Each item accepts only `usdot`, `name`, `phone`, and `email`. An item with any other field is reported in `failed_contacts`.
* Each item needs at least one of `name`, `phone`, or `email` together with `usdot`.
* To leave a field empty, omit it or send `null`. An empty string in `email` is rejected as an invalid email.
* A contact is considered a duplicate when the same USDOT already has a contact for your account with the same `name`, `phone`, or `email`. Duplicates are reported in `failed_contacts`.

{% hint style="info" %}
This endpoint uses `usdot`, `name`, `phone`, and `email`. Field names used elsewhere such as `dot_number`, `contact_name`, `contact_phone`, or `contact_email` are not accepted here.
{% endhint %}

### Request Example:

```bash
curl --location 'https://api.genlogs.io/onboarded-carrier/bulk/contacts' \
--header 'access-token: <your-access-token>' \
--header 'x-api-key: <your-x-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "contacts": [
        {
            "usdot": "123456789",
            "name": "Peter Parker",
            "phone": "3432434234",
            "email": "peter.parker@marvel.com"
        },
        {
            "usdot": "12A45",
            "name": "Mary Jane",
            "email": "mary.jane@marvel.com"
        }
    ]
}'
```

### **Response:**

* **200 OK:** The request was processed. The response lists the contacts that were created in `created_contacts` and the ones that were not in `failed_contacts`. A 200 can have an empty `created_contacts` list when every item failed validation, so always check `failed_contacts`.
* **400 Bad Request:** The request body is invalid (missing `contacts`, empty list, or more than 500 items), or every contact passed validation but all of them already exist. If at least one item failed validation, the response is 200 with `failed_contacts` instead.
* **401 Unauthorized:** The Access-Token is missing, invalid, or expired.
* **403 Forbidden:** The API key is missing or invalid, or your user does not have the required permission.
* **500 Internal Server Error:** An unexpected error prevented the request from being processed.

### **Response Body:**

200 OK – Contacts Created Successfully

* **created\_contacts** (array): Contacts that were created.
  * **id** (string): ID of the created contact.
  * **usdot** (string): USDOT number, without leading zeros.
  * **name** (string): Contact name. Empty string if not provided.
* **failed\_contacts** (array): Contacts that were not created.
  * **index** (integer): Position of the contact in the `contacts` array of the request, starting at 0.
  * **error** (string): Reason the contact was not created.

```json
{
    "created_contacts": [
        {
            "id": "bd849e72-09f0-4d19-8b20-e227cd4ef455",
            "usdot": "123456789",
            "name": "Peter Parker"
        }
    ],
    "failed_contacts": [
        {
            "index": 1,
            "error": "invalid payload: Value error, usdot must contain only digits."
        }
    ]
}
```

Common `error` values in `failed_contacts`:

* `invalid payload: Field required` – the item has no `usdot`.
* `invalid payload: Value error, usdot must contain only digits.`
* `invalid payload: Value error, at least one of name, email, or phone must be provided.`
* `invalid payload: Value error, Additional field(s) 'contact_name' not permitted.`
* `Preferred carrier contact already exists.` – the contact is a duplicate.
* `Unexpected error creating onboarded carrier contact.` – the item could not be saved; retry it.

400 Bad Request

```json
{
    "detail": "Missing required field: contacts"
}
```

```json
{
    "detail": "List should have at least 1 item after validation, not 0"
}
```

```json
{
    "detail": "Value error, Maximum 500 contacts allowed per request"
}
```

```json
{
    "detail": "All provided contacts already exist and no new records were created."
}
```

401 Unauthorized

```json
{
    "detail": "Token is missing!"
}
```

```json
{
    "detail": "Token is invalid or expired"
}
```

403 Forbidden

```json
{
    "detail": "User not allowed to access this endpoint"
}
```

500 Internal Server Error

```json
{
    "detail": "Error creating onboarded carrier contacts."
}
```

## Bulk create onboarded carrier contacts

> Creates multiple onboarded carrier contacts for the authenticated customer in a single request. Each contact entry is validated using the same rules as the single-contact create flow. Valid contacts are created and invalid or duplicate ones are reported per item in failed\_contacts, so a 200 can have an empty created\_contacts list. Each \`usdot\` value must contain digits only, be greater than zero, and be at most 9 digits after normalization.<br>

```json
{"openapi":"3.0.3","info":{"title":"Onboarded Carrier Contacts API","version":"1.1.0"},"servers":[{"url":"https://api.genlogs.io"}],"security":[{"AccessTokenAuth":[],"ApiKeyAuth":[]}],"components":{"securitySchemes":{"AccessTokenAuth":{"type":"apiKey","in":"header","name":"Access-Token","description":"JWT provided directly in the Access-Token header. No \"Bearer\" prefix.\n"}}},"paths":{"/onboarded-carrier/bulk/contacts":{"post":{"summary":"Bulk create onboarded carrier contacts","description":"Creates multiple onboarded carrier contacts for the authenticated customer in a single request. Each contact entry is validated using the same rules as the single-contact create flow. Valid contacts are created and invalid or duplicate ones are reported per item in failed_contacts, so a 200 can have an empty created_contacts list. Each `usdot` value must contain digits only, be greater than zero, and be at most 9 digits after normalization.\n","tags":["Onboarded Carriers"],"requestBody":{"required":true,"description":"List of onboarded carrier contacts to create. The contacts array must contain between 1 and 500 items.\n","content":{"application/json":{"schema":{"type":"object","required":["contacts"],"properties":{"contacts":{"type":"array","minItems":1,"maxItems":500,"description":"List of contacts to create (1 to 500 items).","items":{"type":"object","additionalProperties":false,"required":["usdot"],"properties":{"usdot":{"type":"string","description":"Carrier USDOT number. Must contain digits only, be greater than zero, and be at most 9 digits. Leading zeroes are normalized before persistence.\n","minLength":1,"pattern":"^[0-9]+$"},"name":{"type":"string","nullable":true,"description":"Contact name. Letters, numbers, and spaces only.","pattern":"^[a-zA-Z0-9\\s]+$"},"phone":{"type":"string","nullable":true,"description":"Contact phone number. Digits only, with an optional leading +. Spaces, dashes, and parentheses are removed before validation.\n"},"email":{"type":"string","nullable":true,"format":"email","description":"Contact email address. Omit it or send null to leave it empty; an empty string is rejected.\n"}}}}}}}}},"responses":{"200":{"description":"Contacts processed successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"created_contacts":{"type":"array","description":"List of successfully created contacts.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"usdot":{"type":"string"},"name":{"type":"string"}}}},"failed_contacts":{"type":"array","description":"Per-item errors for contacts that were not created.","items":{"type":"object","properties":{"index":{"type":"integer","description":"Index of the contact in the original payload."},"error":{"type":"string","description":"Human-readable error message for this item."}}}}}}}}},"400":{"description":"Bad Request – Invalid request body, or every persistable contact already exists. If some items fail USDOT validation and others are duplicates, the API returns 200 with per-item errors in failed_contacts instead.\n","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"401":{"description":"Unauthorized – Invalid or missing Access-Token.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"403":{"description":"Forbidden – Missing required permission.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}}}
```