---
title: "Create a scheme identifier"
method: POST
path: "/scheme_identifiers"
tags: ["Scheme Identifier"]
---

# Create a scheme identifier

`POST /scheme_identifiers`

## Request

- Base URL: `https://api.gocardless.com`
- URL: `https://api.gocardless.com/scheme_identifiers`
- Auth: HTTP bearer

Creates a new scheme identifier. The scheme identifier status will be `pending` while GoCardless is
processing the request. Once the scheme identifier is ready to be used the status will be updated to `active`.
At this point, GoCardless will emit a scheme identifier activated event via webhook to notify you of this change.
In Bacs, it will take up to five working days for a scheme identifier to become active. On other schemes, including SEPA,
this happens instantly.

#### Scheme identifier name validations

The `name` field of a scheme identifier can contain alphanumeric characters, spaces and
special characters.

Its maximum length and the special characters it supports depend on the scheme:

| __scheme__        | __maximum length__ | __special characters allowed__                      |
| :---------------- | :----------------- | :-------------------------------------------------- |
| `bacs`            | 18 characters      | `/` `.` `&` `-`                                     |
| `sepa`            | 70 characters      | `/` `?` `:` `(` `)` `.` `,` `+` `&` `<` `>` `'` `"` |
| `ach`             | 16 characters      | `/` `?` `:` `(` `)` `.` `,` `'` `+` `-`             |
| `faster_payments` | 18 characters      | `/` `?` `:` `(` `)` `.` `,` `'` `+` `-`             |

The validation error that gets returned for an invalid name will contain a suggested name
in the metadata that is guaranteed to pass name validations.

You should ensure that the name you set matches the legal name or the trading name of
the creditor, otherwise, there is an increased risk of chargeback.


<p class="restricted-notice"><strong>Restricted</strong>: This endpoint is restricted to GoCardless Embed customers. Please [contact us](https://forms.gocardless.com/l/305971/2023-01-25/535t8n){:target="_blank"} if you are interested in using this product.</p>

## Headers

- `GoCardless-Version` string, required

## Request body

- object
  - `scheme_identifiers` object
    - `name` string, required: The name which appears on customers' bank statements. This should usually be the merchant's trading name.
    - `scheme` 'ach' | 'autogiro' | 'bacs' | 'becs' | 'becs_nz' | 'betalingsservice' | 'faster_payments' | 'pad' | 'pay_to' | 'sepa' | 'sepa_credit_transfer' | 'sepa_instant_credit_transfer', required: The scheme which this scheme identifier applies to.
    - `links` object
      - `creditor` string: <em>required</em> ID of the associated [creditor](https://docs.gocardless.com/docs/api-reference/creditor).

## Response `201`

Resource created successfully

- SchemeIdentifierSingleResourceResponse
  - `scheme_identifiers` SchemeIdentifier: This represents a scheme identifier (e.g. a SUN in Bacs or a CID in SEPA). Scheme identifiers are used to specify the beneficiary name that appears on customers' bank statements.
    - `id` string, required: Unique identifier, usually beginning with "SU".
    - `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.
    - `name` string, required: The name which appears on customers' bank statements. This should usually be the merchant's trading name.
    - `scheme` 'ach' | 'autogiro' | 'bacs' | 'becs' | 'becs_nz' | 'betalingsservice' | 'faster_payments' | 'pad' | 'pay_to' | 'sepa' | 'sepa_credit_transfer' | 'sepa_instant_credit_transfer', required: The scheme which this scheme identifier applies to.
    - `reference` string, nullable, required: The scheme-unique identifier against which payments are submitted.
    - `status` 'pending' | 'active', required: The status of the scheme identifier. Only `active` scheme identifiers will be applied to a creditor and used against payments.
    - `minimum_advance_notice` integer, required: The minimum interval, in working days, between the sending of a pre-notification to the customer, and the charge date of a payment using this scheme identifier. By default, GoCardless sends these notifications automatically. Please see our [compliance requirements](https://docs.gocardless.com/docs/api-reference/compliance-requirements) for more details.
    - `can_specify_mandate_reference` boolean, required: Whether a custom reference can be submitted for mandates using this scheme identifier.
    - `currency` 'AUD' | 'CAD' | 'DKK' | 'EUR' | 'GBP' | 'NZD' | 'SEK' | 'USD', required: The currency of the scheme identifier.
    - `address_line1` string, nullable, required: The first line of the scheme identifier's support address.
    - `address_line2` string, nullable, required: The second line of the scheme identifier's support address.
    - `address_line3` string, nullable, required: The third line of the scheme identifier's support address.
    - `city` string, nullable, required: The city of the scheme identifier's support address.
    - `region` string, nullable, required: The scheme identifier's support address region, county or department.
    - `postal_code` string, nullable, required: The scheme identifier's support postal code.
    - `country_code` string, nullable, required: [ISO 3166-1 alpha-2 code.](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)
    - `email` string, nullable, required: Scheme identifier's support email address.
    - `phone_number` string, nullable, required: Scheme identifier's support phone number.

## 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)