# Retirements

Endpoint: POST /api/ledger/retire
Version: 1.0.0
Security: JWT

## Query parameters:

  - `onBehalfOfAccountId` (string)
    Account id for which the request is being made: defaults to the primary account id of the requester unless specified

## Request fields (application/json):

  - `requests` (array)
    List of requests

  - `requests.certificateSerialNumberRange` (string, required)
    The certificate serial number range: certificate ranges as returned by the holdings call, may not be combined with other ranges, even if contiguous
    Example: "TIGR-1234-GT-SM-08-2024-321-1 to 55"

  - `requests.correlationId` (string)
    Correlation identifier: an opaque value that will be returned in the responses and error messages to correlate the response or error with the corresponding request
    Example: "1"

  - `requests.details` (string)
    Additional details, may be required in some cases: see documentation for more information
    Example: "Retired for Green Energy Program"

  - `requests.emailNotification` (string)
    The e-mail address for notification
    Example: "jdoe@acmecorp.com"

  - `requests.onBehalfOfCorporateEntityId` (integer)
    On Behalf Of Corporate Entity Id: see documentation for allowed values
    Example: "99"

  - `requests.quantity` (number, required)
    The quantity of the transaction
    Example: "55"

  - `requests.reasonCode` (string, required)
    The retire reason code: see documentation for allowed values
    Example: "7"

  - `requests.retirementCertificateType` (string)
    Retirement certificate type: see documentation for allowed values
    Example: "TIGR"

  - `requests.retirementTypeCode` (string, required)
    The retirement type code: GRN, BBO, OTH
    Example: "OTH"

  - `requests.subaccountId` (string, required)
    The subaccount identifier
    Example: "99"

  - `requests.year` (integer, required)
    The year attribute: see documentation for allowed values
    Example: "2024"

## Response 200 fields (application/json):

  - `responses` (array)
    List of responses

  - `responses.certificateSerialNumberRange` (string, required)
    The certificate serial number range: certificate ranges as returned by the holdings call, may not be combined with other ranges, even if contiguous
    Example: "TIGR-1234-GT-SM-08-2024-321-1 to 55"

  - `responses.correlationId` (string)
    Correlation identifier: an opaque value that will be returned in the responses and error messages to correlate the response or error with the corresponding request
    Example: "1"

  - `responses.details` (string)
    Additional details, may be required in some cases: see documentation for more information
    Example: "Retired for Green Energy Program"

  - `responses.emailNotification` (string)
    The e-mail address for notification
    Example: "jdoe@acmecorp.com"

  - `responses.onBehalfOfCorporateEntityId` (integer)
    On Behalf Of Corporate Entity Id: see documentation for allowed values
    Example: "55"

  - `responses.quantity` (number, required)
    The quantity of the transaction
    Example: "55"

  - `responses.reasonCode` (string, required)
    The retire reason code: see documentation for allowed values
    Example: "7"

  - `responses.retirementCertificateType` (string)
    Retirement certificate type: see documentation for allowed values
    Example: "TIGR"

  - `responses.retirementTypeCode` (string, required)
    The retirement type code: GRN, BBO, OTH
    Example: "OTH"

  - `responses.subaccountId` (string, required)
    The subaccount identifier
    Example: "99"

  - `responses.transferId` (string, required)
    The transfer identifier
    Example: "7654"

  - `responses.year` (integer, required)
    The year attribute: see documentation for allowed values
    Example: "2024"

  - `submissionId` (string, required)
    Submission identifier for issue investigation

## Response 400 fields (application/json):

  - `errors` (array)
    List of errors

  - `errors.code` (string, required)
    The error code

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.field` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error message

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `submissionId` (string)
    Submission identifier for issue investigation

## Response 401 fields (application/json):

  - `errors` (array)
    List of errors

  - `errors.code` (string, required)
    The error code

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.field` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error message

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `submissionId` (string)
    Submission identifier for issue investigation

## Response 403 fields (application/json):

  - `errors` (array)
    List of errors

  - `errors.code` (string, required)
    The error code

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.field` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error message

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `submissionId` (string)
    Submission identifier for issue investigation

## Response 413 fields (application/json):

  - `errors` (array)
    List of errors

  - `errors.code` (string, required)
    The error code

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.field` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error message

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `submissionId` (string)
    Submission identifier for issue investigation

## Response 429 fields (application/json):

  - `errors` (array)
    List of errors

  - `errors.code` (string, required)
    The error code

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.field` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error message

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `submissionId` (string)
    Submission identifier for issue investigation

## Response 500 fields (application/json):

  - `errors` (array)
    List of errors

  - `errors.code` (string, required)
    The error code

  - `errors.correlationId` (string)
    The correlation identifier from the input

  - `errors.field` (string)
    The field in error, if applicable

  - `errors.message` (string, required)
    The error message

  - `errors.parameter` (string)
    The parameter in error, if applicable

  - `errors.path` (string)
    The path to the field specifically in error, if applicable

  - `submissionId` (string)
    Submission identifier for issue investigation