# Carrier Contacts Endpoint

Retrieve a list of **Onboarded, Dispatch,** and **FMCSA** contacts for one or more given carriers.

## 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.
- Include **Content-Type: application/json** in the header of the request

## Permissions

The `external-api-carrier-contacts` permission is required to access this endpoint.

## Endpoint

- **URL:** `https://api.genlogs.io/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.

## Request Body **:**

- **usdot_numbers** (string, required): usdot_number(s) separated by commas.

## Understanding contact information

There are no limitations to the number of contacts retrieved in any category (Onboarded, Dispatch, FMCSA). Each array may have zero contacts, one contact, or multiple contacts.

**Carrier Contacts returns three sets of contact information: Dispatch, FMCSA and Onboarded Contacts.**

- **Onboarded Contacts**: values provided from your Onboarded Carrier list, (managed by admins in the UI). If no values are uploaded, they will be blank.
  - `name`
  - `phone`
  - `email`

- **Dispatch contacts**: contacts validated by GenLogs, our customers, or a third party partner. Not available for all carriers:
  - `phone`
  - `email`

- **FMCSA contacts**: contacts provided by the FMCSA. These are shown exactly as registered, including possible null values, multiple semicolon separated values, or values with typos.
  - `name`
  - `phone`
  - `email`

## Response:

- **200 OK:** A JSON object containing 3 sets of carrier contacts.
- **400 Bad Request:** If required parameters are missing or invalid.
- **401 Unauthorized:** If the authentication credentials (Access-Token) is missing or incorrect.
- **403 Forbidden**: If the permission has not been added to your user.
- **500 Internal Server Error:** If there is an issue on the server that prevents processing the request.

## Response Body:

- Data (array of `CarrierContacts` objects): List of carriers contacts grouped by `usdot_number`.
  - `has_dispatch` (string): `Yes` if GenLogs team has confirmed the contact information, otherwise `No`.
  - `onboarded_contact`:
    - `name`
    - `phone`
    - `email`
  - dispatch contact:
    - `phone`
    - `email`
  - fmcsa_contact:
    - `name`
    - `phone`
    - `email`

## Request Example:
```bash
curl --location 'https://api.genlogs.io/carrier/contacts' \
--header 'access-token: <access-token>' \
--header 'x-api-key: <x-api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "usdot_numbers": "10553"
}'
```

## Get contacts for carriers

Returns the contacts related to a carrier (onboarded, dispatch and FMCSA).

### Responses

- **200**: Contacts found
  - `application/json`
  - `data`: object Optional
- **401**: Unauthorized – missing token
  - `application/json`
- **403**: Forbidden – invalid token or insufficient permissions
  - `application/json`
- **500**: Internal Server Error
  - `application/json`

### Response Format:
```json
{
  "data": {
    "12345": {
      "has_dispatch": "Yes",
      "onboarded_contacts": [
        {
          "name": "John Doe",
          "phone": "123-456-7890",
          "email": "john.doe@example.com"
        }
      ],
      "dispatch_contact": [
        {
          "phone": "123-456-7890",
          "email": "john.doe@example.com"
        }
      ],
      "fmcsa_contact": {
        "name": "John Doe",
        "phone": "123-456-7890",
        "email": "john.doe@example.com"
      }
    }
  }
}
```