> ## Documentation Index > Fetch the complete documentation index at: https://docs.cedarai.com/llms.txt > Use this file to discover all available pages before exploring further. # Create customer > Create a customer, optionally with its locations and their addresses. The response is the full customer record, including the `resourceId` of the customer and of each location: store them to update the customer later. Usage notes: - `carrier.resourceId` must be the carrier in the `carrierId` query parameter. - Customer names and SCACs are unique per carrier, and location names are unique per customer: a duplicate returns 400. Create does not match on `externalLocationId`. To find an existing customer, look its name up with List customers, then change it with Update customer. - `printedName` defaults to `name`. Customer and location names cannot contain `/` (412). - `ediId` must be unique across every customer in Cedar; `scac` must be a SCAC Cedar already knows. - An address missing `streetLine1`, `city`, `state` or `zipCode` (and not `AT_PARTIAL`) is rejected with a 500 error. Fix the request rather than retrying it. - Set `usedForBilling: true` on each location you invoice. The first location becomes the default location unless another one has `isDefault: true`. - Cedar also creates two user groups for each new customer, ` Admin` and ` Operator`, shortly after the call returns. Renaming the customer renames them. - A missing permission returns 401. ## OpenAPI ````yaml /user-docs/api-reference/external-openapi.json post /ims/customers/create openapi: 3.1.0 info: title: ARMS External API version: 1.0.0 description: >- OpenAPI specification generated from external API schemas. Endpoints require query parameter carrierId and headers x-arms-api-key and x-arms-assume-user. license: name: Proprietary url: https://cedarai.com servers: - url: https://api-lg.arms.cedarai.com description: Production (US) - url: https://api-lg.arms.cedarai.se description: Production (EU) security: - ApiKeyAuth: [] AssumeUser: [] paths: /ims/customers/create: post: summary: Create customer description: >- Create a customer, optionally with its locations and their addresses. The response is the full customer record, including the `resourceId` of the customer and of each location: store them to update the customer later. Usage notes: - `carrier.resourceId` must be the carrier in the `carrierId` query parameter. - Customer names and SCACs are unique per carrier, and location names are unique per customer: a duplicate returns 400. Create does not match on `externalLocationId`. To find an existing customer, look its name up with List customers, then change it with Update customer. - `printedName` defaults to `name`. Customer and location names cannot contain `/` (412). - `ediId` must be unique across every customer in Cedar; `scac` must be a SCAC Cedar already knows. - An address missing `streetLine1`, `city`, `state` or `zipCode` (and not `AT_PARTIAL`) is rejected with a 500 error. Fix the request rather than retrying it. - Set `usedForBilling: true` on each location you invoice. The first location becomes the default location unless another one has `isDefault: true`. - Cedar also creates two user groups for each new customer, ` Admin` and ` Operator`, shortly after the call returns. Renaming the customer renames them. - A missing permission returns 401. operationId: createCustomer parameters: - $ref: '#/components/parameters/CarrierId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCustomerInput' examples: withBillingLocation: summary: Customer with one billable location value: carrier: resourceId: 1234 name: Acme Chemical ediId: ACMECHEM isTaxExempt: false locations: - name: Acme Chemical - Odessa isDefault: true usedForBilling: true currencyCode: USD email: ap@acme-chemical.example phoneNumber: '4325550100' externalLocationId: NS-CUST-1001 address: streetLine1: 1600 Rail Spur Rd city: Odessa state: TX zipCode: '79761' country: US nameOnly: summary: Customer without locations value: carrier: resourceId: 1234 name: Acme Chemical responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/CreateCustomerOutput' '400': description: >- Bad Request (for example a duplicate name, `scac` or `ediId`, or more than one default location) '401': description: Unauthorized (bad key, carrier not permitted, or missing permission) '404': description: Unknown carrier or `scac` '412': description: A customer or location name contains `/` '500': description: Internal Server Error default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: CarrierId: name: carrierId in: query required: true schema: type: integer description: Carrier identifier; required for all endpoints schemas: CreateCustomerInput: type: object required: - carrier - name properties: carrier: $ref: '#/components/schemas/CarrierReference' name: type: string description: Customer name. Cannot contain `/`. printedName: type: string description: >- Name printed on documents such as invoices (Printed Name in ARMS). Defaults to `name`. scac: type: string description: >- The customer's SCAC. Must be a SCAC Cedar already knows; an unknown SCAC returns 404. ediId: type: string description: >- EDI ID. Must be unique across every customer in Cedar, including deleted customers; a duplicate returns 400. isTaxExempt: type: boolean description: Tax exempt in ARMS. locations: type: array items: $ref: '#/components/schemas/CustomerLocationInput' CreateCustomerOutput: type: object properties: customer: $ref: '#/components/schemas/CustomerDetail' contract: type: object properties: effect: type: string enum: - append resourceType: type: string enum: - Customer Error: type: object properties: message: type: string CarrierReference: type: object required: - resourceId properties: resourceId: type: integer description: 'Your carrier ID: the same value as the `carrierId` query parameter.' CustomerLocationInput: type: object required: - name description: >- A customer location: a site you serve or bill. On Update customer, a location with a `resourceId` changes that location, a location without one is added (set its `customerId`), and locations you leave out of the request are not changed. When you change a location, send all of it, including `isDefault` and its `address`: fields you leave out are reset (`usedForBilling` and `isReportingLocation` to false, `currencyCode` to `USD`) or cleared (`abbreviatedName`, `externalLocationId`, `generalLedgerNumber`). `email`, `phoneNumber` and `customerIdentificationNumbers` keep their values when left out. properties: resourceId: type: integer description: >- Update only. ID of an existing location of this customer. Leave it out to add a new location. customerId: type: integer description: >- Update only, and required when adding a location: the customer's `resourceId`. requestAction: type: string enum: - update - delete default: update description: >- Update only. `delete` removes the location identified by `resourceId`; `name` is still required. name: type: string description: Location name. Cannot contain `/`. abbreviatedName: type: string description: Short name (Abbreviated in ARMS). address: $ref: '#/components/schemas/CustomerAddressInput' isDefault: type: boolean description: >- Marks the customer's default location; a customer has at most one. If no location in the request has `isDefault: true`, the first location in the request is made the default unless it sends `isDefault: false`, and that returns 400 when another location already is the default. To move the default, list the current default with `isDefault: false` before the new one. usedForBilling: type: boolean default: false description: >- Marks the location as billable (Billable in ARMS): a bill-to location you can invoice. currencyCode: type: string default: USD description: ISO 4217 currency code used when invoicing this location. isReportingLocation: type: boolean default: false description: Reporting location in ARMS. email: type: string phoneNumber: type: string maxLength: 11 description: Up to 11 characters, for example `4325550100`. externalLocationId: type: string description: >- Your own system's ID for this location (External location ID in ARMS), for example a NetSuite customer or address ID. Values that start with `up:` are reserved for Union Pacific location IDs and are checked against Union Pacific. generalLedgerNumber: type: string description: Account ID in ARMS. customerIdentificationNumbers: type: array items: type: string description: CIF number prefixes in ARMS. CustomerDetail: type: object description: The full customer record. Fields without a value are left out. properties: resourceId: type: integer description: Customer ID. Use it to update this customer. uuid: type: string name: type: string printedName: type: string scac: type: string ediId: type: string isTaxExempt: type: boolean carrier: $ref: '#/components/schemas/CarrierResource' locations: type: array items: $ref: '#/components/schemas/CustomerLocationDetail' CustomerAddressInput: type: object description: >- A location's address. `streetLine1`, `city`, `state` and `zipCode` are required unless `addressType` is `AT_PARTIAL` or `requestAction` is `delete`. When you change an existing address, send all of it: `name` and `streetLine2` to `streetLine4` are cleared when left out. properties: resourceId: type: integer description: >- Update only. ID of the location's current address, to change it in place. Leave it out to give the location a new address. requestAction: type: string enum: - update - delete default: update description: >- Update only. `delete` removes this address (identified by `resourceId`) from the location. name: type: string streetLine1: type: string streetLine2: type: string streetLine3: type: string streetLine4: type: string city: type: string state: type: string description: State or province code, for example `TX`. zipCode: type: string country: type: string description: Country code, for example `US`. addressType: type: string enum: - AT_CUSTOMER - AT_PARTIAL - AT_CARRIER - AT_PORT - AT_CONTRACTUAL_PORT - AT_STATION description: >- Optional. Use `AT_PARTIAL` to store an address without all of `streetLine1`, `city`, `state` and `zipCode`. CarrierResource: type: object properties: resourceType: type: string enum: - Carrier resourceId: type: integer uuid: type: string description: UUID that complements the legacy numeric resourceId. carrierCode: type: string name: type: string CustomerLocationDetail: type: object properties: resourceId: type: integer uuid: type: string name: type: string abbreviatedName: type: string customer: $ref: '#/components/schemas/CustomerResource' address: $ref: '#/components/schemas/CustomerAddress' isDefault: type: boolean usedForBilling: type: boolean currencyCode: type: string email: type: string phoneNumber: type: string externalLocationId: type: string generalLedgerNumber: type: string customerIdentificationNumbers: type: array items: type: string CustomerResource: type: object properties: resourceType: type: string enum: - Customer resourceId: type: integer uuid: type: string description: UUID that complements the legacy numeric resourceId. name: type: string CustomerAddress: type: object properties: resourceId: type: integer name: type: string streetLine1: type: string streetLine2: type: string streetLine3: type: string streetLine4: type: string city: type: string state: type: string zipCode: type: string country: type: string addressType: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-arms-api-key description: Your ARMS API key AssumeUser: type: apiKey in: header name: x-arms-assume-user description: Email of a user assigned to the appropriate user group ```` ## Related topics - [API Introduction](/user-docs/api-reference/introduction.md) - [Update customer](/api-reference/update-customer.md) - [QuickBooks Web Connector](/user-docs/accounting-integrations/quickbooks-web-connector.md) - [Customer Users](/user-docs/iam/customer-users.md) - [Create a note](/api-reference/lindaservice/create-a-note.md)