> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/chord-oms/api-reference/users.md).
# Users
## Get current user
> This route will return the currently logged in user. This route works\
> for both admin level users and storefront customers that have logged in\
> with the authentication provider that you have configured for your\
> storefront.
```json
{"openapi":"3.0.0","info":{"title":"OMS API","version":"1.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://{host}/api","description":"Chord OMS instance","variables":{"host":{"default":"plant-staging.assembly-api.com","description":"Your tenant host, as configured in Chord OMS. The default is a Chord staging sandbox: replace it with your own host before making real requests."}}}],"security":[{"api-key":[]},{"storefrontLogin":[]}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"This is an admin level API token used for priviliged storefront\noperations. This should never be used in public contexts.\n"},"storefrontLogin":{"type":"apiKey","name":"Authorization","in":"header","description":"This is a user level API token this is issued by whatever authentication\nprovider you have configured for your storefront. It only allows the\ncaller to perform operations on records belonging to them.\n"}},"schemas":{"user":{"title":"User","type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"date_of_birth":{"type":"string","nullable":true,"format":"date"},"bill_address":{"$ref":"#/components/schemas/address"},"ship_address":{"$ref":"#/components/schemas/address"},"store_credit":{"type":"string"},"available_gift_cards":{"type":"array","items":{"$ref":"#/components/schemas/gift_card"}},"roles":{"type":"array","items":{"type":"string"}},"tracking_preferences":{"type":"array","items":{"$ref":"#/components/schemas/tracking_preference"}}}},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"properties":{},"title":"Metadata","description":"A key-value store of additional information. A key can be removed by\nsetting its value to null.\n"},"address":{"type":"object","title":"Address","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"zipcode":{"type":"string"},"country":{"$ref":"#/components/schemas/country"},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_id":{"type":"integer"},"country_iso":{"type":"string"},"phone":{"type":"string","nullable":true},"state":{"$ref":"#/components/schemas/state"},"state_id":{"type":"integer"},"state_name":{"type":"string"},"state_text":{"type":"string"}}},"country":{"type":"object","properties":{"id":{"type":"integer"},"iso":{"type":"string"},"iso3":{"type":"string"},"iso_name":{"type":"string"},"name":{"type":"string"},"numcode":{"type":"integer"}},"title":"Country"},"state":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"abbr":{"type":"string"},"country_id":{"type":"integer"}},"title":"State"},"gift_card":{"type":"object","properties":{"id":{"type":"integer"},"filled":{"type":"boolean"},"amount":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"},"gift_message":{"type":"string"},"send_email_at":{"type":"string"},"purchaser_name":{"type":"string"},"auto_redeem":{"type":"boolean"},"redemption_code":{"type":"string"}}},"tracking_preference":{"type":"object","properties":{"destination":{"type":"string"},"preference":{"type":"boolean"}},"title":"Tracking Preference"}},"responses":{"invalid-api-key":{"description":"Invalid API Key provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"not-found":{"description":"Resource is not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","enum":[500]},"error":{"type":"string"}}}}}}}},"paths":{"/users/me":{"get":{"summary":"Get current user","description":"This route will return the currently logged in user. This route works\nfor both admin level users and storefront customers that have logged in\nwith the authentication provider that you have configured for your\nstorefront.\n","tags":["Users"],"operationId":"getCurrentUser","responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"}}}},"401":{"$ref":"#/components/responses/invalid-api-key"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Get user
> This route allows you to fetch a user by ID. This route is primarly\
> useful for developers that need to pull a user record by ID. This route\
> is not very helpful for storefront applications, as it will only allow\
> fetching of the logged in user by ID. If you need to fetch logged in\
> user information in your storefront, you should use \[\`/users/me\`]\(#/paths/getCurrentUser).
```json
{"openapi":"3.0.0","info":{"title":"OMS API","version":"1.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://{host}/api","description":"Chord OMS instance","variables":{"host":{"default":"plant-staging.assembly-api.com","description":"Your tenant host, as configured in Chord OMS. The default is a Chord staging sandbox: replace it with your own host before making real requests."}}}],"security":[{"api-key":[]},{"storefrontLogin":[]}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"This is an admin level API token used for priviliged storefront\noperations. This should never be used in public contexts.\n"},"storefrontLogin":{"type":"apiKey","name":"Authorization","in":"header","description":"This is a user level API token this is issued by whatever authentication\nprovider you have configured for your storefront. It only allows the\ncaller to perform operations on records belonging to them.\n"}},"schemas":{"user":{"title":"User","type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"date_of_birth":{"type":"string","nullable":true,"format":"date"},"bill_address":{"$ref":"#/components/schemas/address"},"ship_address":{"$ref":"#/components/schemas/address"},"store_credit":{"type":"string"},"available_gift_cards":{"type":"array","items":{"$ref":"#/components/schemas/gift_card"}},"roles":{"type":"array","items":{"type":"string"}},"tracking_preferences":{"type":"array","items":{"$ref":"#/components/schemas/tracking_preference"}}}},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"properties":{},"title":"Metadata","description":"A key-value store of additional information. A key can be removed by\nsetting its value to null.\n"},"address":{"type":"object","title":"Address","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"zipcode":{"type":"string"},"country":{"$ref":"#/components/schemas/country"},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_id":{"type":"integer"},"country_iso":{"type":"string"},"phone":{"type":"string","nullable":true},"state":{"$ref":"#/components/schemas/state"},"state_id":{"type":"integer"},"state_name":{"type":"string"},"state_text":{"type":"string"}}},"country":{"type":"object","properties":{"id":{"type":"integer"},"iso":{"type":"string"},"iso3":{"type":"string"},"iso_name":{"type":"string"},"name":{"type":"string"},"numcode":{"type":"integer"}},"title":"Country"},"state":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"abbr":{"type":"string"},"country_id":{"type":"integer"}},"title":"State"},"gift_card":{"type":"object","properties":{"id":{"type":"integer"},"filled":{"type":"boolean"},"amount":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"},"gift_message":{"type":"string"},"send_email_at":{"type":"string"},"purchaser_name":{"type":"string"},"auto_redeem":{"type":"boolean"},"redemption_code":{"type":"string"}}},"tracking_preference":{"type":"object","properties":{"destination":{"type":"string"},"preference":{"type":"boolean"}},"title":"Tracking Preference"}},"responses":{"invalid-api-key":{"description":"Invalid API Key provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"not-found":{"description":"Resource is not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","enum":[500]},"error":{"type":"string"}}}}}}}},"paths":{"/users/{user_id}":{"get":{"summary":"Get user","description":"This route allows you to fetch a user by ID. This route is primarly\nuseful for developers that need to pull a user record by ID. This route\nis not very helpful for storefront applications, as it will only allow\nfetching of the logged in user by ID. If you need to fetch logged in\nuser information in your storefront, you should use [`/users/me`](#/paths/getCurrentUser).\n","operationId":"getUser","tags":["Users"],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"}}}},"401":{"$ref":"#/components/responses/invalid-api-key"},"404":{"$ref":"#/components/responses/not-found"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Delete user
> Deletes a user.
```json
{"openapi":"3.0.0","info":{"title":"OMS API","version":"1.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://{host}/api","description":"Chord OMS instance","variables":{"host":{"default":"plant-staging.assembly-api.com","description":"Your tenant host, as configured in Chord OMS. The default is a Chord staging sandbox: replace it with your own host before making real requests."}}}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"This is an admin level API token used for priviliged storefront\noperations. This should never be used in public contexts.\n"}},"responses":{"no-content":{"description":"Successful operation with no content returned"},"invalid-api-key":{"description":"Invalid API Key provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"not-found":{"description":"Resource is not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"delete-restriction":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","enum":[500]},"error":{"type":"string"}}}}}}}},"paths":{"/users/{user_id}":{"delete":{"summary":"Delete user","description":"Deletes a user.","operationId":"delete-user","tags":["Users"],"responses":{"204":{"$ref":"#/components/responses/no-content"},"401":{"$ref":"#/components/responses/invalid-api-key"},"404":{"$ref":"#/components/responses/not-found"},"422":{"$ref":"#/components/responses/delete-restriction"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Update user
> This route allows you to update a user record. Chord's OMS keeps admins\
> and customers in the same user system, differentiating them with \`roles\`.\
> \
> \## Does updating a user update external systems?\
> \
> Yes, it does. Upon a successful user record update, Chord's API will fire\
> a "User Updated" event to Segment. From there, you are able to wire up\
> pushing this update to external providers, like Iterable or Klayvio.
```json
{"openapi":"3.0.0","info":{"title":"OMS API","version":"1.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://{host}/api","description":"Chord OMS instance","variables":{"host":{"default":"plant-staging.assembly-api.com","description":"Your tenant host, as configured in Chord OMS. The default is a Chord staging sandbox: replace it with your own host before making real requests."}}}],"security":[{"api-key":[]},{"storefrontLogin":[]}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"This is an admin level API token used for priviliged storefront\noperations. This should never be used in public contexts.\n"},"storefrontLogin":{"type":"apiKey","name":"Authorization","in":"header","description":"This is a user level API token this is issued by whatever authentication\nprovider you have configured for your storefront. It only allows the\ncaller to perform operations on records belonging to them.\n"}},"schemas":{"UpdateUserInput":{"type":"object","description":"The UpdateUserInput schema can accept attributes either as top level keys\nor nested inside of a `user` key, which mirrors the semantics of [`CreateUserInput`](#/components/schemas/CreateUserInput).\n","oneOf":[{"title":"User input properties nested inside of top level user key","type":"object","required":["user"],"properties":{"user":{"$ref":"#/components/schemas/UserInputProperties"}}},{"title":"User properties in the top level","allOf":[{"$ref":"#/components/schemas/UserInputProperties"}]}]},"UserInputProperties":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"password":{"type":"string","description":"This password must pass Chord's password complexity requirements,\nwhich are as follows.\n\n- 1 uppercase character\n- 1 special character\n- 1 number\n- 8 characters minimum\n\nIf the user is not going to login to the OMS, as they are a customer,\nyou should generate a random string that meets these requirements.\n"},"password_confirmation":{"type":"string","description":"This field must match the `password` field. It can be a matching\nrandom string if the user will not be logging in with a password.\n"},"bill_address_attributes":{"$ref":"#/components/schemas/address-input"},"ship_address_attributes":{"$ref":"#/components/schemas/address-input"}}},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"properties":{},"title":"Metadata","description":"A key-value store of additional information. A key can be removed by\nsetting its value to null.\n"},"address-input":{"type":"object","title":"Address Input","required":["address1","city"],"properties":{"name":{"type":"string","description":"The full name of the user. You must provide this field OR one of OR both of `firstname` and `lastname` for\nthe payload to be valid.\n\nThis field will override `firstname` and `lastname` if both are provided.\n"},"firstname":{"type":"string","description":"The first name of the user. This field will be ignored if `name` is provided.\n"},"lastname":{"type":"string","description":"The last name of the user. This field will be ignored if `name` is provided.\n"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"state_name":{"type":"string","description":"Either the name of the state (\"New York\") or it's abbreviation (\"NY\").\n\nThis field (or `state_id`) is required if [`/api/countries/{country_id}/states`](#/paths/list-country-states)\nreturns `\"states_required\": true` in it's body.\n"},"state_id":{"type":"integer","description":"This ID can be found by calling [`/api/countries/{country_id}/states`](#/paths/list-country-states).\n\nThis field (or `state_name`) is required if the above endpoint returns `\"states_required\": true`.\n"},"country_id":{"type":"integer","description":"This ID can be found by calling [`/api/countries`](#/paths/list-countries). Either `country_id` OR `country_iso`\nmust be provided for this payload to be valid.\n"},"country_iso":{"type":"string","description":"The [ISO 3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) that the\nuser resides in. This list can be fetched from [`/api/countries`](#/paths/list-countries), where the key is\n`iso`.\n\nThis field OR `country_id` must be provided for this payload to be valid.\n"},"zipcode":{"type":"string","nullable":true,"description":"This field is required if the country requires a ZIP code, like the United States (`233`).\n"},"phone":{"type":"string","nullable":true},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"user":{"title":"User","type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"date_of_birth":{"type":"string","nullable":true,"format":"date"},"bill_address":{"$ref":"#/components/schemas/address"},"ship_address":{"$ref":"#/components/schemas/address"},"store_credit":{"type":"string"},"available_gift_cards":{"type":"array","items":{"$ref":"#/components/schemas/gift_card"}},"roles":{"type":"array","items":{"type":"string"}},"tracking_preferences":{"type":"array","items":{"$ref":"#/components/schemas/tracking_preference"}}}},"address":{"type":"object","title":"Address","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"zipcode":{"type":"string"},"country":{"$ref":"#/components/schemas/country"},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_id":{"type":"integer"},"country_iso":{"type":"string"},"phone":{"type":"string","nullable":true},"state":{"$ref":"#/components/schemas/state"},"state_id":{"type":"integer"},"state_name":{"type":"string"},"state_text":{"type":"string"}}},"country":{"type":"object","properties":{"id":{"type":"integer"},"iso":{"type":"string"},"iso3":{"type":"string"},"iso_name":{"type":"string"},"name":{"type":"string"},"numcode":{"type":"integer"}},"title":"Country"},"state":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"abbr":{"type":"string"},"country_id":{"type":"integer"}},"title":"State"},"gift_card":{"type":"object","properties":{"id":{"type":"integer"},"filled":{"type":"boolean"},"amount":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"},"gift_message":{"type":"string"},"send_email_at":{"type":"string"},"purchaser_name":{"type":"string"},"auto_redeem":{"type":"boolean"},"redemption_code":{"type":"string"}}},"tracking_preference":{"type":"object","properties":{"destination":{"type":"string"},"preference":{"type":"boolean"}},"title":"Tracking Preference"}},"responses":{"invalid-api-key":{"description":"Invalid API Key provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"not-found":{"description":"Resource is not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"unprocessable-entity":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"errors":{"type":"object"}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","enum":[500]},"error":{"type":"string"}}}}}}}},"paths":{"/users/{user_id}":{"patch":{"summary":"Update user","description":"This route allows you to update a user record. Chord's OMS keeps admins\nand customers in the same user system, differentiating them with `roles`.\n\n## Does updating a user update external systems?\n\nYes, it does. Upon a successful user record update, Chord's API will fire\na \"User Updated\" event to Segment. From there, you are able to wire up\npushing this update to external providers, like Iterable or Klayvio.\n","operationId":"updateUser","tags":["Users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserInput"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"}}}},"401":{"$ref":"#/components/responses/invalid-api-key"},"404":{"$ref":"#/components/responses/not-found"},"422":{"$ref":"#/components/responses/unprocessable-entity"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## List users
> Lists all users.
```json
{"openapi":"3.0.0","info":{"title":"OMS API","version":"1.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://{host}/api","description":"Chord OMS instance","variables":{"host":{"default":"plant-staging.assembly-api.com","description":"Your tenant host, as configured in Chord OMS. The default is a Chord staging sandbox: replace it with your own host before making real requests."}}}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"This is an admin level API token used for priviliged storefront\noperations. This should never be used in public contexts.\n"}},"parameters":{"page":{"name":"page","in":"query","schema":{"type":"integer","default":1}},"per_page":{"name":"per_page","in":"query","schema":{"type":"integer","default":25}}},"schemas":{"pagination-data":{"title":"Pagination data","type":"object","properties":{"count":{"type":"integer"},"current_page":{"type":"integer"},"pages":{"type":"integer"},"per_page":{"type":"integer","description":"This will match the value passed in to the `per_page` query parameter.\n"},"total_count":{"type":"integer"}}},"user":{"title":"User","type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"date_of_birth":{"type":"string","nullable":true,"format":"date"},"bill_address":{"$ref":"#/components/schemas/address"},"ship_address":{"$ref":"#/components/schemas/address"},"store_credit":{"type":"string"},"available_gift_cards":{"type":"array","items":{"$ref":"#/components/schemas/gift_card"}},"roles":{"type":"array","items":{"type":"string"}},"tracking_preferences":{"type":"array","items":{"$ref":"#/components/schemas/tracking_preference"}}}},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"properties":{},"title":"Metadata","description":"A key-value store of additional information. A key can be removed by\nsetting its value to null.\n"},"address":{"type":"object","title":"Address","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"zipcode":{"type":"string"},"country":{"$ref":"#/components/schemas/country"},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_id":{"type":"integer"},"country_iso":{"type":"string"},"phone":{"type":"string","nullable":true},"state":{"$ref":"#/components/schemas/state"},"state_id":{"type":"integer"},"state_name":{"type":"string"},"state_text":{"type":"string"}}},"country":{"type":"object","properties":{"id":{"type":"integer"},"iso":{"type":"string"},"iso3":{"type":"string"},"iso_name":{"type":"string"},"name":{"type":"string"},"numcode":{"type":"integer"}},"title":"Country"},"state":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"abbr":{"type":"string"},"country_id":{"type":"integer"}},"title":"State"},"gift_card":{"type":"object","properties":{"id":{"type":"integer"},"filled":{"type":"boolean"},"amount":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"},"gift_message":{"type":"string"},"send_email_at":{"type":"string"},"purchaser_name":{"type":"string"},"auto_redeem":{"type":"boolean"},"redemption_code":{"type":"string"}}},"tracking_preference":{"type":"object","properties":{"destination":{"type":"string"},"preference":{"type":"boolean"}},"title":"Tracking Preference"}},"responses":{"invalid-api-key":{"description":"Invalid API Key provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/users":{"get":{"summary":"List users","description":"Lists all users.","operationId":"list-users","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/pagination-data"},{"type":"object","properties":{"users":{"type":"array","items":{"$ref":"#/components/schemas/user"}}}}]}}}},"401":{"$ref":"#/components/responses/invalid-api-key"}}}}}}
```
## Create user
> This route allows you to create a user. By default, this user will be\
> created without roles, which will put them in the role of a customer.\
> \
> When spinning up your Chord store, it is not strictly necessary required\
> to import all of your existing customers, as they will be created upon\
> interactions with your storefront, such as purchases. Chord's admin\
> provides the ability to upload a CSV of users.\
> \
> For legacy Chord purposes, customers must be created with passwords,\
> even if you are using an OAuth or passwordless login service for your\
> storefront. To get around this, generate a random string for the user's\
> \`password\` and \`password\_confirmation\`.
```json
{"openapi":"3.0.0","info":{"title":"OMS API","version":"1.1"},"tags":[{"name":"Users"}],"servers":[{"url":"https://{host}/api","description":"Chord OMS instance","variables":{"host":{"default":"plant-staging.assembly-api.com","description":"Your tenant host, as configured in Chord OMS. The default is a Chord staging sandbox: replace it with your own host before making real requests."}}}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"http","scheme":"bearer","description":"This is an admin level API token used for priviliged storefront\noperations. This should never be used in public contexts.\n"}},"schemas":{"CreateUserInput":{"type":"object","required":["user"],"properties":{"user":{"required":["email","password","password_confirmation"],"allOf":[{"$ref":"#/components/schemas/UserInputProperties"}]}}},"UserInputProperties":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string","nullable":true},"date_of_birth":{"type":"string","format":"date","nullable":true},"password":{"type":"string","description":"This password must pass Chord's password complexity requirements,\nwhich are as follows.\n\n- 1 uppercase character\n- 1 special character\n- 1 number\n- 8 characters minimum\n\nIf the user is not going to login to the OMS, as they are a customer,\nyou should generate a random string that meets these requirements.\n"},"password_confirmation":{"type":"string","description":"This field must match the `password` field. It can be a matching\nrandom string if the user will not be logging in with a password.\n"},"bill_address_attributes":{"$ref":"#/components/schemas/address-input"},"ship_address_attributes":{"$ref":"#/components/schemas/address-input"}}},"metadata":{"type":"object","nullable":true,"additionalProperties":true,"properties":{},"title":"Metadata","description":"A key-value store of additional information. A key can be removed by\nsetting its value to null.\n"},"address-input":{"type":"object","title":"Address Input","required":["address1","city"],"properties":{"name":{"type":"string","description":"The full name of the user. You must provide this field OR one of OR both of `firstname` and `lastname` for\nthe payload to be valid.\n\nThis field will override `firstname` and `lastname` if both are provided.\n"},"firstname":{"type":"string","description":"The first name of the user. This field will be ignored if `name` is provided.\n"},"lastname":{"type":"string","description":"The last name of the user. This field will be ignored if `name` is provided.\n"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"state_name":{"type":"string","description":"Either the name of the state (\"New York\") or it's abbreviation (\"NY\").\n\nThis field (or `state_id`) is required if [`/api/countries/{country_id}/states`](#/paths/list-country-states)\nreturns `\"states_required\": true` in it's body.\n"},"state_id":{"type":"integer","description":"This ID can be found by calling [`/api/countries/{country_id}/states`](#/paths/list-country-states).\n\nThis field (or `state_name`) is required if the above endpoint returns `\"states_required\": true`.\n"},"country_id":{"type":"integer","description":"This ID can be found by calling [`/api/countries`](#/paths/list-countries). Either `country_id` OR `country_iso`\nmust be provided for this payload to be valid.\n"},"country_iso":{"type":"string","description":"The [ISO 3166-1 Alpha-2 country code](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) that the\nuser resides in. This list can be fetched from [`/api/countries`](#/paths/list-countries), where the key is\n`iso`.\n\nThis field OR `country_id` must be provided for this payload to be valid.\n"},"zipcode":{"type":"string","nullable":true,"description":"This field is required if the country requires a ZIP code, like the United States (`233`).\n"},"phone":{"type":"string","nullable":true},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true}}},"user":{"title":"User","type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string","format":"email"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"$ref":"#/components/schemas/metadata"},"notes":{"type":"string"},"name":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"date_of_birth":{"type":"string","nullable":true,"format":"date"},"bill_address":{"$ref":"#/components/schemas/address"},"ship_address":{"$ref":"#/components/schemas/address"},"store_credit":{"type":"string"},"available_gift_cards":{"type":"array","items":{"$ref":"#/components/schemas/gift_card"}},"roles":{"type":"array","items":{"type":"string"}},"tracking_preferences":{"type":"array","items":{"$ref":"#/components/schemas/tracking_preference"}}}},"address":{"type":"object","title":"Address","properties":{"id":{"type":"integer"},"name":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"zipcode":{"type":"string"},"country":{"$ref":"#/components/schemas/country"},"alternative_phone":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"country_id":{"type":"integer"},"country_iso":{"type":"string"},"phone":{"type":"string","nullable":true},"state":{"$ref":"#/components/schemas/state"},"state_id":{"type":"integer"},"state_name":{"type":"string"},"state_text":{"type":"string"}}},"country":{"type":"object","properties":{"id":{"type":"integer"},"iso":{"type":"string"},"iso3":{"type":"string"},"iso_name":{"type":"string"},"name":{"type":"string"},"numcode":{"type":"integer"}},"title":"Country"},"state":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"abbr":{"type":"string"},"country_id":{"type":"integer"}},"title":"State"},"gift_card":{"type":"object","properties":{"id":{"type":"integer"},"filled":{"type":"boolean"},"amount":{"type":"string"},"recipient_email":{"type":"string"},"recipient_name":{"type":"string"},"gift_message":{"type":"string"},"send_email_at":{"type":"string"},"purchaser_name":{"type":"string"},"auto_redeem":{"type":"boolean"},"redemption_code":{"type":"string"}}},"tracking_preference":{"type":"object","properties":{"destination":{"type":"string"},"preference":{"type":"boolean"}},"title":"Tracking Preference"}},"responses":{"invalid-api-key":{"description":"Invalid API Key provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}},"unprocessable-entity":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"errors":{"type":"object"}}}}}},"InternalServerError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"number","enum":[500]},"error":{"type":"string"}}}}}}}},"paths":{"/users":{"post":{"summary":"Create user","description":"This route allows you to create a user. By default, this user will be\ncreated without roles, which will put them in the role of a customer.\n\nWhen spinning up your Chord store, it is not strictly necessary required\nto import all of your existing customers, as they will be created upon\ninteractions with your storefront, such as purchases. Chord's admin\nprovides the ability to upload a CSV of users.\n\nFor legacy Chord purposes, customers must be created with passwords,\neven if you are using an OAuth or passwordless login service for your\nstorefront. To get around this, generate a random string for the user's\n`password` and `password_confirmation`.\n","operationId":"createUser","tags":["Users"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserInput"}}}},"responses":{"201":{"description":"User has been successfully created","headers":{"Location":{"schema":{"type":"string","nullable":true}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/user"}}}},"401":{"$ref":"#/components/responses/invalid-api-key"},"422":{"$ref":"#/components/responses/unprocessable-entity"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.chord.co/chord-oms/api-reference/users.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.