# Create ISA transfer

Creates an ISA transfer, moving all or part of an end user's existing ISA into an Upvest Stocks and Shares ISA while preserving their current-year allowance.
Set `transfer_type` to `ISA_EXTERNAL` for a transfer between ISA managers, which requires `counterparty`, or to `ISA_INTERNAL` for a transfer within the same ISA manager, which requires `transfer_value` and `details`. Only cash transfers are supported, so `transfer_method` must be `CASH`.
See the ISA transfers implementation guide ([TOL](https://docs.upvest.co/products/tol/guides/tax_wrappers/tax_wrappers_isa_transfers_implementation) / [BYOL](https://docs.upvest.co/products/byol/guides/tax_wrappers/tax_wrappers_isa_transfers_implementation)) for the required fields per transfer type.

Endpoint: POST /isa/transfers
Version: 1.159.0
Security: oauth-client-credentials

## Security:

  - `oauth-client-credentials` (unknown)
    oauth2 scopes: isa_transfers:admin

## Header parameters:

  - `idempotency-key` (string, required)
    A UUID to be used as an idempotency key.  This prevents a duplicate request from being replayed.
https://docs.upvest.co/documentation/concepts/api_concepts/idempotency

  - `upvest-client-id` (string, required)
    Your client ID, issued by Upvest. Identifies the client making the request. Universally Unique Identifier (UUID).

  - `Authorization` (string, required)
    Bearer (access) token from the OAuth flow with correct scopes.
https://datatracker.ietf.org/doc/html/rfc6750

  - `signature` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-http-header

  - `signature-input` (string, required)
    https://tools.ietf.org/id/draft-ietf-httpbis-message-signatures-01.html#name-the-signature-input-http-he

  - `upvest-api-version` (string)
    Upvest API version (Note: Do not include quotation marks)

## Request fields (application/json):

  - `direction` (string, required)
    Direction of the ISA transfer
* INCOMING - Transfer is incoming to the user.
* OUTGOING - Transfer is outgoing from the user.
    Enum: "INCOMING", "OUTGOING"

  - `transfer_type` (string, required)
    Type of the securities transfer
* ISA_INTERNAL - Transfer occurs within the same ISA manager.
* ISA_EXTERNAL - Transfer occurs across different ISA managers, via Equisoft or others.
    Enum: "ISA_INTERNAL", "ISA_EXTERNAL"

  - `transfer_value` (string)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `currency` (string, required)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* GBP - Great British Pound
    Enum: "GBP"

  - `transfer_method` (string, required)
    Method of the ISA transfer
* CASH - Cash transfer.

Other methods can be supported in the future, e.g. IN_SPECIE
    Enum: "CASH"

  - `user_id` (string, required)
    Unique identifier of the user, as a UUID.

  - `account_group_id` (string, required)
    Universally Unique Identifier (UUID) of the account group.

  - `reference` (string)
    Random string reference on which API clients can build logic.

  - `counterparty` (object)
    The other ISA manager involved in an external ISA transfer.

  - `counterparty.account_number` (string, required)
    The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.

  - `transfer_date` (string, required)
    The date when end user initiated the transfer. Relevant for tax year's end reporting. If not sent it will be the time we create the transfer internally on our side. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `details` (object)
    The subscription details of an internal ISA transfer, used to apportion the transfer against the current tax year's allowance.

  - `details.current_year_subscription` (object, required)
    Details related to the current year’s subscription being transferred.
Required if transfer_type is ISA_INTERNAL.

  - `details.current_year_subscription.transfer_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `details.current_year_subscription.first_subscription_at` (string)
    The date of the first subscription made to the ISA in the current tax year. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)
Required if transfer_type is ISA_INTERNAL.

## Response 200:

  - `200` (unknown)
    ISA Transfer created

## Response 200 fields (application/json):

  - `id` (string, required)
    The unique identifier of the ISA transfer, as a UUID.

  - `created_at` (string, required)
    Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `updated_at` (string, required)
    Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `direction` (string, required)
    Direction of the ISA transfer
* INCOMING - Transfer is incoming to the user.
* OUTGOING - Transfer is outgoing from the user.
    Enum: "INCOMING", "OUTGOING"

  - `status` (string, required)
    Status of the transfer
* NEW - Transfer is created.
* DISCOVERY - Discovery with the ceding provider where information about the transfer is being exchanged and reviewed. Only relevant if type ISA_EXTERNAL.
* DISCOVERY_CONFIRMED - Discovery is completed and transfer request is accepted by the ceding provider. Only relevant if type ISA_EXTERNAL.
* INSTRUCTED - Transfer is instructed to the ceding provider.
* PROCESSING - Transfer instruction is confirmed by the ceding provider. Transfer is being processed.
* SETTLED - Transfer is completed.
    Enum: "NEW", "DISCOVERY", "DISCOVERY_CONFIRMED", "INSTRUCTED", "PROCESSING", "SETTLED"

  - `transfer_type` (string, required)
    Type of the securities transfer
* ISA_INTERNAL - Transfer occurs within the same ISA manager.
* ISA_EXTERNAL - Transfer occurs across different ISA managers, via Equisoft or others.
    Enum: "ISA_INTERNAL", "ISA_EXTERNAL"

  - `transfer_value` (string)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `currency` (string, required)
    Alphabetic three-letter [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.
* GBP - Great British Pound
    Enum: "GBP"

  - `transfer_method` (string, required)
    Method of the ISA transfer
* CASH - Cash transfer.

Other methods can be supported in the future, e.g. IN_SPECIE
    Enum: "CASH"

  - `user_id` (string, required)
    Unique identifier of the user, as a UUID.

  - `account_group_id` (string, required)
    Universally Unique Identifier (UUID) of the account group.

  - `reference` (string, required)
    Random string reference on which API clients can build logic.

  - `counterparty` (object)
    The other ISA manager involved in an external ISA transfer.

  - `counterparty.account_number` (string, required)
    The account number is composed of valid Swift charset with a max length of 28 if provided. The account number helps other brokers identify the owner of the assets.

  - `transfer_date` (string, required)
    The date when end user initiated the transfer. Relevant for tax year's end reporting. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)

  - `details` (object)
    The subscription details of an internal ISA transfer, used to apportion the transfer against the current tax year's allowance.

  - `details.current_year_subscription` (object, required)
    Details related to the current year’s subscription being transferred.
Required if transfer_type is ISA_INTERNAL.

  - `details.current_year_subscription.transfer_amount` (string, required)
    A positive cash amount, as a decimal string with up to two decimal places.

  - `details.current_year_subscription.first_subscription_at` (string)
    The date of the first subscription made to the ISA in the current tax year. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html)
Required if transfer_type is ISA_INTERNAL.

## Response 200 headers (application/json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 400:

  - `400` (unknown)
    Bad Request. The incoming request had a malformed parameter/object.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 400 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 401:

  - `401` (unknown)
    Unauthorized. The caller has not been authenticated.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 401 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 403:

  - `403` (unknown)
    Forbidden. The caller has been authenticated but is not allowed to take the requested action.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 403 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 404:

  - `404` (unknown)
    Not Found. The requested resource could not be found.

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 404 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 406:

  - `406` (unknown)
    Not Acceptable. The resource does not have a current representation that would be acceptable to the user agent. "Accept" header defined unsupported value.

## Response 406 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 406 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 429:

  - `429` (unknown)
    Too Many Requests. The caller has exceeded their quota for the time period and has been throttled.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 429 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 500:

  - `500` (unknown)
    Internal Server Error. The service encountered an unexpected error.

## Response 500 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 500 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 503:

  - `503` (unknown)
    Service Unavailable. The service handling for this request cannot be reached at this time.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 503 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7

## Response 504:

  - `504` (unknown)
    Gateway Timeout. The service gateway has reached its internal timeout.

## Response 504 fields (application/problem+json):

  - `type` (string, required)
    URL to a document describing the error condition.

  - `status` (integer, required)
    Transmission of the HTTP status code so that all information can be found in one place, but also to correct changes in the status code due to the use of proxy servers.

  - `title` (string)
    A short, human-readable title for the general error type; the title should not change for given types.

  - `detail` (string)
    A human-readable description of the specific error.

  - `instance` (string)
    This optional key may be present, with a unique URI for the specific error; this will often point to an error log for that specific response.

  - `request_id` (string)
    Correlation ID for the original request.

## Response 504 headers (application/problem+json):

  - `upvest-request-id` (string, required)
    Example: 169ae4c7-ebd7-4041-94da-25369653eba7