# Customer Source: https://docs.gocardless.com/docs/api-reference/customer ## Create a customer `POST /customers` Creates a new customer object. ### Request body Wrap request body attributes in a `customers` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | No | Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer. | | `given_name` | string | No | Customer's first name. Required unless a `company_name` is provided. | | `family_name` | string | No | Customer's surname. Required unless a `company_name` is provided. | | `company_name` | string | No | Customer's company name. Required unless a `given_name` and `family_name` are provided. For Canadian customers, the use of a `company_name` value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD"). | | `address_line1` | string | No | The first line of the customer's address. | | `address_line2` | string | No | The second line of the customer's address. | | `address_line3` | string | No | The third line of the customer's address. | | `city` | string | No | The city of the customer's address. | | `region` | string | No | The customer's address region, county or department. For US customers a 2 letter [ISO3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code is required (e.g. `CA` for California). | | `postal_code` | string | No | The customer's postal code. | | `country_code` | string | No | [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | | `language` | string | No | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see [compliance requirements](#appendix-compliance-requirements)). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the `country_code` (if supplied) or default to "en". | | `phone_number` | string | No | [ITU E.123](https://en.wikipedia.org/wiki/E.123) formatted phone number, including country code. | | `swedish_identity_number` | string | No | For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set. | | `danish_identity_number` | string | No | For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK). | | `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. | ### Responses | Status | Description | | --- | --- | | 201 | Resource created successfully | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## List customers `GET /customers` Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your customers. ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Get a single customer `GET /customers/{customer_id}` Retrieves the details of an existing customer. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `customer_id` | path | string | Yes | The customer id | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Update a customer `PUT /customers/{customer_id}` Updates a customer object. Supports all of the fields supported when creating a customer. ### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `customer_id` | path | string | Yes | The customer id | ### Request body Wrap request body attributes in a `customers` object. | Field | Type | Required | Description | | --- | --- | --- | --- | | `email` | string | No | Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer. | | `given_name` | string | No | Customer's first name. Required unless a `company_name` is provided. | | `family_name` | string | No | Customer's surname. Required unless a `company_name` is provided. | | `company_name` | string | No | Customer's company name. Required unless a `given_name` and `family_name` are provided. For Canadian customers, the use of a `company_name` value will mean that any mandate created from this customer will be considered to be a "Business PAD" (otherwise, any mandate will be considered to be a "Personal PAD"). | | `address_line1` | string | No | The first line of the customer's address. | | `address_line2` | string | No | The second line of the customer's address. | | `address_line3` | string | No | The third line of the customer's address. | | `city` | string | No | The city of the customer's address. | | `region` | string | No | The customer's address region, county or department. For US customers a 2 letter [ISO3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) state code is required (e.g. `CA` for California). | | `postal_code` | string | No | The customer's postal code. | | `country_code` | string | No | [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) | | `language` | string | No | [ISO 639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) code. Used as the language for notification emails sent by GoCardless if your organisation does not send its own (see [compliance requirements](#appendix-compliance-requirements)). Currently only "en", "fr", "de", "pt", "es", "it", "nl", "da", "nb", "sl", "sv" are supported. If this is not provided, the language will be chosen based on the `country_code` (if supplied) or default to "en". | | `phone_number` | string | No | [ITU E.123](https://en.wikipedia.org/wiki/E.123) formatted phone number, including country code. | | `swedish_identity_number` | string | No | For Swedish customers only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer's bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set. | | `danish_identity_number` | string | No | For Danish customers only. The civic/company number (CPR or CVR) of the customer. Must be supplied if the customer's bank account is denominated in Danish krone (DKK). | | `metadata` | object | No | Key-value store of custom data. Up to 3 keys are permitted, with key names up to 50 characters and values up to 500 characters. | ### Responses | Status | Description | | --- | --- | | 200 | Successful response | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error | --- ## Remove a customer `DELETE /customers/{customer_id}` Removed customers will not appear in search results or lists of customers (in our API or exports), and it will not be possible to load an individually removed customer by ID.

The action of removing a customer cannot be reversed, so please use with care.

### Parameters | Name | Location | Type | Required | Description | | --- | --- | --- | --- | --- | | `customer_id` | path | string | Yes | The customer id | ### Responses | Status | Description | | --- | --- | | 204 | Resource deleted successfully (no content) | | 400 | Bad Request | | 401 | Unauthorised | | 404 | Not found | | 422 | Validation Error | | 500 | Internal Error |