# Scheme Identifier

Source: https://docs.gocardless.com/docs/api-reference/scheme-identifier

## Create a scheme identifier

`POST /scheme_identifiers`

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.

### Request body

Wrap request body attributes in a `scheme_identifiers` object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | The name which appears on customers' bank statements. This should usually be the merchant's trading name. |
| `scheme` | string | No | The scheme which this scheme identifier applies to. |
| `links` | object | No |  |

### Responses

| Status | Description |
| --- | --- |
| 201 | Resource created successfully |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## List scheme identifiers

`GET /scheme_identifiers`

Returns a [cursor-paginated](#api-usage-cursor-pagination) list of your scheme identifiers.

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |

---

## Get a single scheme identifier

`GET /scheme_identifiers/{scheme_identifier_id}`

Retrieves the details of an existing scheme identifier.

### Parameters

| Name | Location | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `scheme_identifier_id` | path | string | Yes | The scheme identifier id |

### Responses

| Status | Description |
| --- | --- |
| 200 | Successful response |
| 400 | Bad Request |
| 401 | Unauthorised |
| 404 | Not found |
| 422 | Validation Error |
| 500 | Internal Error |