> ## Documentation Index > Fetch the complete documentation index at: https://docs.alvys.com/llms.txt > Use this file to discover all available pages before exploring further. # Create customer > Create a new customer record in Alvys with company profile, billing address, contacts, credit terms, and default rate agreements for future loads. The Create Customer endpoint adds a new business company (a Customer or a Broker/3PL) to your account. On success it returns the created record together with the optimistic-concurrency token (`ETag`) you will need for any later update or delete. For more information on how versioning works and how to include it in your requests, please refer to the [Versioning](/docs/versioning) page. Per-tenant, per-`Type` uniqueness is enforced on `CompanyNumber`, `ExternalId`, and `(Name + Zip)`. A request that would create a duplicate is rejected with `409 Conflict` and the identifier of the existing customer. *** ### Request Parameters The following parameter is required in the URL path: | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------- | | version | String | Yes | The version of the API. | *** ### Request Body The request body accepts the following fields. Only `Name` is required. | Field | Type | Required | Description | | ---------------------- | --------------- | -------- | -------------------------------------------------------------------------------- | | Name | String | Yes | The customer name. Must be 200 characters or fewer. | | Type | String | No | The customer type. One of "Customer" or "Broker/3PL". | | CompanyNumber | String | No | A reference/registration number for the company. Must be 32 characters or fewer. | | Status | String | No | The customer status. One of "Active" or "Inactive". | | BillingAddress | Object | No | The billing address of the customer. | | BillingAddress.Street | String | No | The street line of the billing address. | | BillingAddress.City | String | No | The city of the billing address. | | BillingAddress.State | String | No | The state of the billing address. | | BillingAddress.Zip | String | No | The postal code of the billing address. | | BillingAddress.Country | String | No | ISO country code of the billing address. Defaults to "US". | | Email | Array of String | No | A list of email addresses associated with the customer. | | Phone | Array of String | No | A list of phone numbers associated with the customer. | | Fax | String | No | The fax number of the customer. | | ExternalId | String | No | An external reference identifier. Must be 100 characters or fewer. | *** ### Example CURL Request ```bash theme={null} curl --location 'https://integrations.alvys.com/api/p/v1/customers' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data-raw '{ "Name": "Acme Logistics", "Type": "Broker/3PL", "CompanyNumber": "ACME-001", "Status": "Active", "BillingAddress": { "Street": "123 Main St", "City": "Dallas", "State": "TX", "Zip": "75201", "Country": "US" }, "Email": ["billing@acme.example"], "Phone": ["+1-214-555-0100"], "ExternalId": "EXT-ACME-001" }' ``` Replace `YOUR_ACCESS_TOKEN` with your actual Bearer token. *** ### Response Fields A successful request returns the created customer. The optimistic-concurrency token is returned both on the HTTP `ETag` response header and in the `ETag` body field, so you can use it on a follow-up `If-Match` without an extra GET. | Field | Type | Description | | ---------------------- | ------------------ | ------------------------------------------------------- | | Id | String | The unique identifier of the created customer. | | ETag | String | The optimistic-concurrency token for the new record. | | Name | String | The name of the customer. | | CompanyNumber | String | The company number of the customer. | | Type | String | The type of customer ("Customer" or "Broker/3PL"). | | Status | String | The raw persisted status of the customer. | | BillingAddress | Object | The billing address of the customer. | | BillingAddress.Street | String | The street line of the billing address. | | BillingAddress.City | String | The city of the billing address. | | BillingAddress.State | String | The state of the billing address. | | BillingAddress.ZipCode | String | The postal code of the billing address. | | Email | Array | A list of email addresses associated with the customer. | | Phone | Array | A list of phone numbers associated with the customer. | | Fax | String | The fax number of the customer. | | DateCreated | String (Date-Time) | The date and time when the customer was created. | | DateModified | String (Date-Time) | The date and time of this write. | | InvoicingInformation | Object | The invoicing information for the customer. | | ExternalId | String | The external identifier associated with the customer. | *** ### Example Response **201 Created** ```json theme={null} { "Id": "01fec4d332ed49ff96595c8d4434ea96", "ETag": "\"00000000-0000-0000-0000-000000000001\"", "Name": "Acme Logistics", "CompanyNumber": "ACME-001", "Type": "Broker/3PL", "Status": "Active", "BillingAddress": { "Street": "123 Main St", "City": "Dallas", "State": "TX", "ZipCode": "75201" }, "Email": ["billing@acme.example"], "Phone": ["+1-214-555-0100"], "Fax": null, "DateCreated": "2025-09-08T19:38:34.529Z", "DateModified": "2025-09-08T19:38:34.529Z", "InvoicingInformation": null, "ExternalId": "EXT-ACME-001" } ``` *** ### Status Codes | Status | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | 201 | The customer was created. | | 400 | The request body failed validation. | | 401 | The request was not authenticated. | | 403 | The caller lacks permission to create customers. | | 409 | A customer with the same `CompanyNumber`, `ExternalId`, or `(Name + Zip)` already exists. The response includes the existing `customerId`. | *** ### Rate Limits All endpoints are subject to rate limits to protect the API from traffic spikes. For detailed information on rate limits, please refer to the [Rate Limits](/docs/rate-limits) section. This page is interactive, allowing you to try a request by completing the fields for the parameters below. As you fill out the parameters, the CURL command on the right side of the page will be automatically updated. ## OpenAPI ````yaml POST /api/p/v{version}/customers openapi: 3.0.1 info: title: Alvys description: >- Alvys provides a robust set of REST APIs to allow you to integrate Alvys into virtually any platform. These APIs cover most of Alvys' major product areas with additional endpoints being added regularly based on customer requests. contact: name: Alvys Support url: https://www.alvys.com/resources/contact/ version: v1 servers: - url: https://integrations.alvys.com description: Public API Server - url: https://api.alvys.com/ description: Public API Server security: - Public: [] tags: - name: Authentication description: Obtain an OAuth 2.0 access token for the Alvys Public API. - name: Carrier Settlement Statements description: >- Search carrier settlement statements and retrieve a single statement by number. - name: Carriers description: Read carrier records, search carriers, and manage carrier documents. - name: Customers description: Create, read, update, delete, and search customer records. - name: Deductions description: >- Create one-time deductions and search or delete existing deduction records. - name: DispatchPreferences description: Dispatch preferences endpoints for reading dispatch rules and preferences. - name: Driver Settlement Statements description: >- Search driver settlement statements and retrieve a single statement by number. - name: Drivers description: >- Read driver records, search drivers and driver events, and manage driver documents. - name: Fuel description: Read and search fuel transactions. - name: Invoices description: >- Read invoices, create carrier invoices, and record carrier and customer payments. - name: Loads description: Read, update, search loads, and manage load documents and notes. - name: Locations description: Read and search company location details. - name: Maintenance description: Read and search maintenance records. - name: Tenders description: Create, accept, reject, cancel, update, and search inbound EDI tenders. - name: Tolls description: Read and search toll transactions. - name: Trailers description: Read trailers, search trailer events, and manage trailer documents. - name: Trips description: >- Read, search trips, manage trip documents, and record stop appointments, arrivals, and departures. - name: Trucks description: Read trucks, search truck events, and manage truck documents. - name: Users description: List and search users. - name: Visibility description: >- Read inbound and outbound visibility history and search outbound visibility errors. - name: Webhooks description: >- Create, read, update, delete, enable, disable, verify, test, and rotate secrets for webhook subscriptions; read event types, delivery logs, and health metrics. paths: /api/p/v{version}/customers: post: tags: - Customers summary: Create customer parameters: - name: version in: path description: API version (e.g., 1.0) required: true schema: type: string default: '1.0' example: '1.0' requestBody: content: application/json-patch+json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Customers.CustomerWriteRequest application/json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Customers.CustomerWriteRequest text/json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Customers.CustomerWriteRequest application/*+json: schema: allOf: - $ref: >- #/components/schemas/Alvys.Models.Customers.CustomerWriteRequest required: true responses: '201': description: Created content: application/json: schema: $ref: >- #/components/schemas/Alvys.Models.Customers.CustomerWriteResponse '400': description: Bad Request content: application/json: schema: $ref: >- #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' '429': description: Too Many Requests content: application/problem+json: schema: $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails' security: - Public: [] components: schemas: Alvys.Models.Customers.CustomerWriteRequest: type: object properties: Name: type: string nullable: true Type: type: string nullable: true CompanyNumber: type: string nullable: true Status: type: string nullable: true BillingAddress: allOf: - $ref: >- #/components/schemas/Alvys.Models.Customers.CustomerWriteAddressRequest nullable: true Email: type: array items: type: string nullable: true Phone: type: array items: type: string nullable: true Fax: type: string nullable: true ExternalId: type: string nullable: true additionalProperties: false Alvys.Models.Customers.CustomerWriteResponse: required: - CompanyNumber - Email - ETag - Id - Name - Phone - Status - Type type: object properties: Id: type: string ETag: type: string Name: type: string CompanyNumber: type: string Type: type: string Status: type: string BillingAddress: allOf: - $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress' nullable: true Email: type: array items: type: string Phone: type: array items: type: string Fax: type: string nullable: true DateCreated: type: string format: date-time nullable: true DateModified: type: string format: date-time nullable: true InvoicingInformation: allOf: - $ref: >- #/components/schemas/Alvys.Models.Customers.InvoicingInformationResponse nullable: true ExternalId: type: string nullable: true additionalProperties: false Microsoft.AspNetCore.Mvc.ValidationProblemDetails: required: - Errors type: object properties: Errors: type: object additionalProperties: type: array items: type: string Type: type: string nullable: true Title: type: string nullable: true Status: type: integer format: int32 nullable: true Detail: type: string nullable: true Instance: type: string nullable: true additionalProperties: {} Microsoft.AspNetCore.Mvc.ProblemDetails: type: object properties: Type: type: string nullable: true Title: type: string nullable: true Status: type: integer format: int32 nullable: true Detail: type: string nullable: true Instance: type: string nullable: true additionalProperties: {} Alvys.Models.Customers.CustomerWriteAddressRequest: required: - City - Country - State - Street - Zip type: object properties: Street: type: string City: type: string State: type: string Zip: type: string Country: type: string additionalProperties: false Alvys.Features.Locations.ShortAddress: required: - City - State - Street - ZipCode type: object properties: Street: type: string City: type: string State: type: string ZipCode: type: string additionalProperties: false Alvys.Models.Customers.InvoicingInformationResponse: required: - EmailAddresses type: object properties: Address: allOf: - $ref: '#/components/schemas/Alvys.Features.Locations.ShortAddress' nullable: true EmailAddresses: type: array items: type: string PhoneNumber: type: string nullable: true InvoicingName: type: string nullable: true InvoicingNameAlias: type: string nullable: true PaymentType: type: string nullable: true PaymentTermsInDays: type: integer format: int32 nullable: true additionalProperties: false securitySchemes: Public: type: http scheme: bearer bearerFormat: JWT description: >- OAuth 2.0 client-credentials access token. Obtain one from https://auth.alvys.com/oauth/token (grant_type=client_credentials, audience=https://api.alvys.com/public/), then paste it here. The playground sends it as `Authorization: Bearer `. ````