> 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.md).

# Create Onboarded Carriers

Create an onboarded carrier contact associated with a specific USDOT. This endpoint allows customers to add their own validated contact information.

### **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/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:**

* **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, so `(555) 123-4567` is accepted and saved as `5551234567`.
* **email** (string, optional): Contact email address. Must be a valid email address.

#### **Validation rules**

* Only `usdot`, `name`, `phone`, and `email` are accepted. Any other field rejects the whole request with a 400.
* At least one of `name`, `phone`, or `email` must be provided 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 rejected with a 400.

{% 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/contacts' \
--header 'access-token: <your-access-token>' \
--header 'x-api-key: <your-x-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "usdot": "123456789",
    "name": "Peter Parker",
    "phone": "3432434234",
    "email": "peter.parker@marvel.com"
}'
```

### **Response:**

* **200 OK:** The contact was created. Returns the created contact.
* **400 Bad Request:** A field is missing, invalid, or not allowed, or the contact already exists.
* **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 contact from being created.

### **Response Body:**

200 OK – Contact Created Successfully

* **contact** (object):
  * **id** (string): ID of the created contact.
  * **name** (string): Contact name. Empty string if not provided.
  * **phone** (string): Contact phone number. Empty string if not provided.
  * **email** (string): Contact email address. Empty string if not provided.

```json
{
  "contact": {
    "id": "bd849e72-09f0-4d19-8b20-e227cd4ef455",
    "name": "Peter Parker",
    "phone": "3432434234",
    "email": "peter.parker@marvel.com"
  }
}
```

400 Bad Request

Only the first validation error is returned.

`usdot` is missing:

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

`usdot` is not valid:

```json
{
    "detail": "Value error, usdot must contain only digits."
}
```

```json
{
    "detail": "Value error, usdot must be a positive integer."
}
```

```json
{
    "detail": "Value error, usdot must be at most 9 digits."
}
```

None of `name`, `phone`, or `email` was provided:

```json
{
    "detail": "Value error, at least one of name, email, or phone must be provided."
}
```

A field that is not allowed was sent:

```json
{
    "detail": "Value error, Additional field(s) 'contact_name' not permitted."
}
```

`name` or `phone` has an invalid format:

```json
{
    "detail": "Value error, name must contain only letters, numbers, and spaces (no special characters)."
}
```

```json
{
    "detail": "Value error, phone must contain only numbers, with an optional leading + (no spaces or special characters)."
}
```

`email` is not a valid email address:

```json
{
    "detail": "value is not a valid email address: <reason>"
}
```

The contact already exists:

```json
{
    "detail": "Preferred carrier contact already exists."
}
```

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 contact."
}
```

## Create an onboarded carrier contact

> Creates a new onboarded carrier contact for the authenticated customer. Requires a valid JWT token and the appropriate permission. The \`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.0.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/contacts":{"post":{"summary":"Create an onboarded carrier contact","description":"Creates a new onboarded carrier contact for the authenticated customer. Requires a valid JWT token and the appropriate permission. The `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,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Only usdot, name, phone, and email are accepted; any other field is rejected with a 400. At least one of name, phone, or email must be provided together with usdot.\n","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":"Contact created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"}}}}}}}},"400":{"description":"Bad Request – A field is missing, invalid, or not allowed, or the contact already exists. Only the first validation error is returned.\n","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"401":{"description":"Unauthorized – Access-Token is missing, invalid, or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"403":{"description":"Forbidden – The user lacks 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"}}}}}}}}}}}
```