# Securities Transfers events

Securities Transfers events

Endpoint: POST Securities Transfers events
Version: 1.97.0

## Request fields (application/json):

  - `id` (string, required)
    Event unique identifier

  - `created_at` (string, required)
    Date and time when the event 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)

  - `type` (string, required)
    Event type
    Enum: "SECURITIES_TRANSFER.NEW", "SECURITIES_TRANSFER.PROCESSING", "SECURITIES_TRANSFER.SETTLED", "SECURITIES_TRANSFER.CANCELLED", "SECURITIES_TRANSFER.DATA_CHANGED"

  - `object` (object, required)

  - `object.id` (string, required)
    Securities transfer request unique identifier.

  - `object.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)

  - `object.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)

  - `object.user_id` (string, required)
    User unique identifier.

  - `object.account_id` (string, required)
    Account unique identifier.

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

  - `object.status` (string, required)
    Status of the securities transfer
* NEW - Securities transfer is created but not started processing.
* PROCESSING - Securities transfer is in processing.
* SETTLED - Securities transfer was successfully settled.
* CANCELLED - Securities transfer was cancelled.
    Enum: "NEW", "PROCESSING", "SETTLED", "CANCELLED"

  - `object.transfer_type` (string, required)
    Type of the securities transfer
* NO_OWNER_CHANGE - No change of ownership.
    Enum: "NO_OWNER_CHANGE"

  - `object.instrument_id` (string, required)
    ISIN or other identity (depends on instrument_id_type) of the security to be transferred.

  - `object.instrument_id_type` (string, required)
    Type of the instrument_id
* ISIN - International Securities Identification Number
    Enum: "ISIN"

  - `object.quantity` (string, required)
    The quantity of instrument to move in or out.

  - `object.counterparty` (any, required)
    Counterparty for securities transfer. The type field determines which counterparty variant is present in the payload.

  - `object.settlement_reference` (string, required)
    Unique identifier of the securities transfer set by API consumers. Useful for API consumers to build special logic on top of it.
NOTE: For automatic incoming transfers where API users will subscribe to the corresponding webhook, the value is set by Upvest!

  - `object.trade_date` (string, required)
    The forecast date when the trade takes place. Date in YYYY-MM-DD format.

  - `object.settlement_date` (string, required)
    The forecast date when the settlement takes place. Date in YYYY-MM-DD format.

  - `object.quantity_settled` (string)
    The quantity of instruments settled.

  - `object.place_of_settlement` (string)
    Business Identifier Code (also known as SWIFT-BIC, BIC, SWIFT ID or SWIFT code) [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362).

  - `object.settlement_counterparties` (object)
    Settlement counterparties for the securities transfer.
When settlement_counterparties is provided, settlement_agent is required. Other participants are optional but must respect the following dependency rules:
* settlement_custodian presence requires settlement_party to be present.
* settlement_intermediary_1 presence requires settlement_custodian to be present.
* settlement_intermediary_2 presence requires settlement_intermediary_1 to be present.

 Note: settlement_custodian can be provided without an explicit settlement_party since the default counterparty field at transfer level serves as the settlement party.

  - `object.settlement_counterparties.settlement_agent` (object, required)
    A participant in the settlement chain, identified by an identification and an optional account.

  - `object.settlement_counterparties.settlement_agent.identification` (object, required)
    Identification of a settlement counterparty.
* BIC Party identified by BIC.
* PROPRIETARY Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS Party identified by name and address.

  - `object.settlement_counterparties.settlement_agent.identification.type` (string, required)
    Type of identification.
* BIC - Party identified by BIC.
* PROPRIETARY - Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS - Party identified by name and address.
    Enum: "BIC", "PROPRIETARY", "NAME_AND_ADDRESS"

  - `object.settlement_counterparties.settlement_agent.identification.value` (string, required)
    Identification value. The format depends on the type:
* For BIC: A valid BIC code.
* For PROPRIETARY: A proprietary identifier under the given scheme.
* For NAME_AND_ADDRESS: Name and address of the party.

  - `object.settlement_counterparties.settlement_agent.identification.scheme` (string)
    ISO Data Source Scheme code. Required when type is PROPRIETARY. Identifies the source of the proprietary identification (e.g. CRST, DAKV, CEDE).

  - `object.settlement_counterparties.settlement_agent.account` (object)
    Account of a settlement counterparty.
* SAFE - Safekeeping account.

  - `object.settlement_counterparties.settlement_agent.account.type` (string, required)
    Type of the account.
* SAFE - Safekeeping account.
    Enum: "SAFE"

  - `object.settlement_counterparties.settlement_agent.account.value` (string, required)
    Account identifier value.

  - `object.settlement_counterparties.settlement_custodian` (object)
    A participant in the settlement chain, identified by an identification and an optional account.

  - `object.settlement_counterparties.settlement_custodian.identification` (object, required)
    Identification of a settlement counterparty.
* BIC Party identified by BIC.
* PROPRIETARY Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS Party identified by name and address.

  - `object.settlement_counterparties.settlement_custodian.identification.type` (string, required)
    Type of identification.
* BIC - Party identified by BIC.
* PROPRIETARY - Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS - Party identified by name and address.
    Enum: "BIC", "PROPRIETARY", "NAME_AND_ADDRESS"

  - `object.settlement_counterparties.settlement_custodian.identification.value` (string, required)
    Identification value. The format depends on the type:
* For BIC: A valid BIC code.
* For PROPRIETARY: A proprietary identifier under the given scheme.
* For NAME_AND_ADDRESS: Name and address of the party.

  - `object.settlement_counterparties.settlement_custodian.identification.scheme` (string)
    ISO Data Source Scheme code. Required when type is PROPRIETARY. Identifies the source of the proprietary identification (e.g. CRST, DAKV, CEDE).

  - `object.settlement_counterparties.settlement_custodian.account` (object)
    Account of a settlement counterparty.
* SAFE - Safekeeping account.

  - `object.settlement_counterparties.settlement_custodian.account.type` (string, required)
    Type of the account.
* SAFE - Safekeeping account.
    Enum: "SAFE"

  - `object.settlement_counterparties.settlement_custodian.account.value` (string, required)
    Account identifier value.

  - `object.settlement_counterparties.settlement_intermediary_1` (object)
    A participant in the settlement chain, identified by an identification and an optional account.

  - `object.settlement_counterparties.settlement_intermediary_1.identification` (object, required)
    Identification of a settlement counterparty.
* BIC Party identified by BIC.
* PROPRIETARY Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS Party identified by name and address.

  - `object.settlement_counterparties.settlement_intermediary_1.identification.type` (string, required)
    Type of identification.
* BIC - Party identified by BIC.
* PROPRIETARY - Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS - Party identified by name and address.
    Enum: "BIC", "PROPRIETARY", "NAME_AND_ADDRESS"

  - `object.settlement_counterparties.settlement_intermediary_1.identification.value` (string, required)
    Identification value. The format depends on the type:
* For BIC: A valid BIC code.
* For PROPRIETARY: A proprietary identifier under the given scheme.
* For NAME_AND_ADDRESS: Name and address of the party.

  - `object.settlement_counterparties.settlement_intermediary_1.identification.scheme` (string)
    ISO Data Source Scheme code. Required when type is PROPRIETARY. Identifies the source of the proprietary identification (e.g. CRST, DAKV, CEDE).

  - `object.settlement_counterparties.settlement_intermediary_1.account` (object)
    Account of a settlement counterparty.
* SAFE - Safekeeping account.

  - `object.settlement_counterparties.settlement_intermediary_1.account.type` (string, required)
    Type of the account.
* SAFE - Safekeeping account.
    Enum: "SAFE"

  - `object.settlement_counterparties.settlement_intermediary_1.account.value` (string, required)
    Account identifier value.

  - `object.settlement_counterparties.settlement_intermediary_2` (object)
    A participant in the settlement chain, identified by an identification and an optional account.

  - `object.settlement_counterparties.settlement_intermediary_2.identification` (object, required)
    Identification of a settlement counterparty.
* BIC Party identified by BIC.
* PROPRIETARY Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS Party identified by name and address.

  - `object.settlement_counterparties.settlement_intermediary_2.identification.type` (string, required)
    Type of identification.
* BIC - Party identified by BIC.
* PROPRIETARY - Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS - Party identified by name and address.
    Enum: "BIC", "PROPRIETARY", "NAME_AND_ADDRESS"

  - `object.settlement_counterparties.settlement_intermediary_2.identification.value` (string, required)
    Identification value. The format depends on the type:
* For BIC: A valid BIC code.
* For PROPRIETARY: A proprietary identifier under the given scheme.
* For NAME_AND_ADDRESS: Name and address of the party.

  - `object.settlement_counterparties.settlement_intermediary_2.identification.scheme` (string)
    ISO Data Source Scheme code. Required when type is PROPRIETARY. Identifies the source of the proprietary identification (e.g. CRST, DAKV, CEDE).

  - `object.settlement_counterparties.settlement_intermediary_2.account` (object)
    Account of a settlement counterparty.
* SAFE - Safekeeping account.

  - `object.settlement_counterparties.settlement_intermediary_2.account.type` (string, required)
    Type of the account.
* SAFE - Safekeeping account.
    Enum: "SAFE"

  - `object.settlement_counterparties.settlement_intermediary_2.account.value` (string, required)
    Account identifier value.

  - `object.settlement_counterparties.settlement_party` (object)
    A participant in the settlement chain, identified by an identification and an optional account.

  - `object.settlement_counterparties.settlement_party.identification` (object, required)
    Identification of a settlement counterparty.
* BIC Party identified by BIC.
* PROPRIETARY Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS Party identified by name and address.

  - `object.settlement_counterparties.settlement_party.identification.type` (string, required)
    Type of identification.
* BIC - Party identified by BIC.
* PROPRIETARY - Party identified by a proprietary code under a Data Source Scheme.
* NAME_AND_ADDRESS - Party identified by name and address.
    Enum: "BIC", "PROPRIETARY", "NAME_AND_ADDRESS"

  - `object.settlement_counterparties.settlement_party.identification.value` (string, required)
    Identification value. The format depends on the type:
* For BIC: A valid BIC code.
* For PROPRIETARY: A proprietary identifier under the given scheme.
* For NAME_AND_ADDRESS: Name and address of the party.

  - `object.settlement_counterparties.settlement_party.identification.scheme` (string)
    ISO Data Source Scheme code. Required when type is PROPRIETARY. Identifies the source of the proprietary identification (e.g. CRST, DAKV, CEDE).

  - `object.settlement_counterparties.settlement_party.account` (object)
    Account of a settlement counterparty.
* SAFE - Safekeeping account.

  - `object.settlement_counterparties.settlement_party.account.type` (string, required)
    Type of the account.
* SAFE - Safekeeping account.
    Enum: "SAFE"

  - `object.settlement_counterparties.settlement_party.account.value` (string, required)
    Account identifier value.

  - `object.actual_settlement_date` (string)
    The date when the transfer settled, only known in SETTLED status. Date in YYYY-MM-DD format.

  - `webhook_id` (string, required)
    Webhook unique identifier.


## Response 200 fields