--- title: "Add a mandate import entry" method: POST path: "/mandate_import_entries" tags: ["Mandate Import Entry"] --- # Add a mandate import entry `POST /mandate_import_entries` ## Request - Base URL: `https://api.gocardless.com` - URL: `https://api.gocardless.com/mandate_import_entries` - Auth: HTTP bearer For an existing [mandate import](https://docs.gocardless.com/docs/api-reference/mandate-import), this endpoint can be used to add individual mandates to be imported into GoCardless. You can add no more than 30,000 rows to a single mandate import. If you attempt to go over this limit, the API will return a `record_limit_exceeded` error. ## Headers - `GoCardless-Version` string, required ## Request body - object - `mandate_import_entries` object - `links` object, required - `mandate_import` string, required: Unique identifier, beginning with "IM". - `record_identifier` string, nullable: A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters. - `mandate` object - `reference` string, nullable: Unique reference. Different schemes have different length and [character set](https://docs.gocardless.com/docs/api-reference/character-sets) requirements. GoCardless will generate a unique reference satisfying the different scheme requirements if this field is left blank. - `authorisation_source` 'web' | 'telephone' | 'paper': This field is ACH specific, sometimes referred to as [SEC code](https://www.moderntreasury.com/learn/sec-codes). This is the way that the payer gives authorisation to the merchant. web: Authorisation is Internet Initiated or via Mobile Entry (maps to SEC code: WEB) telephone: Authorisation is provided orally over telephone (maps to SEC code: TEL) paper: Authorisation is provided in writing and signed, or similarly authenticated (maps to SEC code: PPD) - `metadata` CustomerMetadata: 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. - `customer` object, required - `given_name` string, nullable: Customer's first name. Required unless a `company_name` is provided. - `family_name` string, nullable: Customer's surname. Required unless a `company_name` is provided. - `company_name` string, nullable: 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"). - `email` string, nullable: Customer's email address. Required in most cases, as this allows GoCardless to send notifications to this customer. - `language` string, nullable: [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](https://docs.gocardless.com/docs/api-reference/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". - `address_line1` string: The first line of the customer's address. Required if mandate import scheme is either `bacs` or `sepa`. - `address_line2` string, nullable: The second line of the customer's address. - `address_line3` string, nullable: The third line of the customer's address. - `city` string, nullable: The city of the customer's address. - `region` string, nullable: 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: The customer's postal code. Required if mandate import scheme is either `bacs` or `sepa`. - `country_code` string, nullable: [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) - `phone_number` string, nullable: [ITU E.123](https://en.wikipedia.org/wiki/E.123) formatted phone number, including country code. - `swedish_identity_number` string, nullable: 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, nullable: 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` CustomerMetadata: 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. - `bank_account` object, required - `account_holder_name` string, required: Name of the account holder, as known by the bank. The full name provided when the customer is created is stored and is available via the API, but is transliterated, upcased, and truncated to 18 characters in bank submissions. This field is required unless the request includes a [customer bank account token](https://docs.gocardless.com/docs/collect-payments/integration-types/javascript-drop-in-flow). - `account_number` string, nullable: Bank account number - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`. - `bank_code` string, nullable: Bank code - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`. - `branch_code` string, nullable: Branch code - see [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details) for more information. Alternatively you can provide an `iban`. - `country_code` string, nullable: [ISO 3166-1 alpha-2 code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements). Defaults to the country code of the `iban` if supplied, otherwise is required. - `iban` string, nullable: International Bank Account Number. Alternatively you can provide [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details). IBANs are not accepted for Swedish bank accounts denominated in SEK - you must supply [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#sweden). - `account_type` 'savings' | 'checking', nullable: Bank account type. Required for USD-denominated bank accounts. Must not be provided for bank accounts in other currencies. See [local details](https://docs.gocardless.com/docs/api-reference/local-bank-details#united-states) for more information. - `metadata` CustomerMetadata: 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. - `amendment` object - `original_mandate_reference` string, required: The unique SEPA reference for the mandate being amended. Required if mandate import scheme is `sepa`. - `original_creditor_id` string, required: The creditor identifier of the direct debit originator. Required if mandate import scheme is `sepa`. - `original_creditor_name` string, required: Data about the original mandate to be moved or modified. ## Response `201` Resource created successfully - MandateImportEntrySingleResourceResponse - `mandate_import_entries` MandateImportEntry: Mandate Import Entries are added to a [Mandate Import](https://docs.gocardless.com/docs/api-reference/mandate-import). Each entry corresponds to one mandate to be imported into GoCardless. To import a mandate you will need:
  1. Identifying information about the customer (name/company and address)
  2. Bank account details, consisting of an account holder name and either an IBAN or local bank details
  3. Amendment details (SEPA only)
We suggest you provide a `record_identifier` (which is unique within the context of a single mandate import) to help you to identify mandates that have been created once the import has been processed by GoCardless. You can [list the mandate import entries](https://docs.gocardless.com/docs/api-reference/mandate-import-entry#list-all-mandate-import-entries), match them up in your system using the `record_identifier`, and look at the `links` fields to find the mandate, customer and customer bank account that have been imported.

Restricted: This API is currently only available for approved integrators - please get in touch if you would like to use this API.

- `record_identifier` string, nullable, required: A unique identifier for this entry, which you can use (once the import has been processed by GoCardless) to identify the records that have been created. Limited to 255 characters. - `created_at` string, date-time, required: Fixed [timestamp](https://docs.gocardless.com/docs/api-reference/data-conventions#dates-and-times), recording when this resource was created. - `links` MandateImportEntryLinks, required: Related resources - `mandate_import` string, required: The ID of the mandate import. This is returned when you [create a Mandate Import](https://docs.gocardless.com/docs/api-reference/mandate-import#create-a-new-mandate-import). - `mandate` string: The ID of the mandate which was created when the mandate import was processed. - `customer` string: The ID of the customer which was created when the mandate import was processed. - `customer_bank_account` string: The ID of the customer bank account which was created when the mandate import was processed. - `processing_errors` MandateImportEntryProcessingErrors, nullable, required: Per-resource processing errors ## Other responses - `400`: Bad Request - `401`: Unauthorised - `404`: Not found - `422`: Validation Error - `500`: Internal Error --- [API](https://skmtc.dev/gocardless/apis/gocardless-api.md) - [All operations](https://skmtc.dev/gocardless/apis/gocardless-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gocardless/apis/gocardless-api/revisions/4dd3dae45364?raw)