---
title: "Set the subscription of a business partner"
url: "https://apiportal.six-group.com/apis/settlement-info-reporting-ch-v1/versions/52cbfb5f-8e19-42e4-a1fa-bded916e761f/operations/setSubscription"
---

> Full API specification: https://apiportal.six-group.com/apis/settlement-info-reporting-ch-v1/versions/52cbfb5f-8e19-42e4-a1fa-bded916e761f.md

# Set the subscription of a business partner

`POST` `/bulk-subscription/securities/bulk-set`

Operation ID: `setSubscription`

Sets the subscription (list of securities identified by their ISIN). The previous subscription is overwritten if and only if the operation is successful. If the request body includes bad data (typically, one element in the array is an invalid ISIN), 400 is returned and the subscription is not updated.

## Header parameters

- `X-Correlation-Id` (string, optional) - Correlation identifier for the request

## Request body (required)

Content types: `application/vnd.api+json`

## Responses

- `204` - No Content
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `413` - Content Too Large
- `429` - Too Many Requests
- `500` - Internal Server Error
- `503` - Service Unavailable
- `504` - Gateway Timeout

## OpenAPI definition

```yaml
openapi: 3.0.2
info:
  title: Security Settlement Information - External API
  version: 1.0.7
servers:
  - url: https://api.six-group.com/custody/cockpit/setlInfo/v1
  - url: https://api.p2p.six-group.com/custody/cockpit/setlInfo/v1
  - url: https://api.fip.six-group.com/custody/cockpit/setlInfo/v1
paths:
  /bulk-subscription/securities/bulk-set:
    post:
      tags:
        - BulkSubscriptionManagement
      summary: Set the subscription of a business partner
      description: >-
        Sets the subscription (list of securities identified by their ISIN). The
        previous subscription is overwritten if and only if the operation is
        successful.


        If the request body includes bad data (typically, one element in the
        array is an invalid ISIN), 400 is returned and the subscription is not
        updated.
      operationId: setSubscription
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: "#/components/schemas/SubscriptionRequestBody"
        required: true
      responses:
        "204":
          $ref: "#/components/responses/Http204NoContent"
        "400":
          $ref: "#/components/responses/Http400ErrorResponse_BulkSet"
        "401":
          $ref: "#/components/responses/Http401ErrorResponse"
        "403":
          $ref: "#/components/responses/Http403ErrorResponse"
        "413":
          $ref: "#/components/responses/Http413ErrorResponse"
        "429":
          $ref: "#/components/responses/Http429ErrorResponse"
        "500":
          $ref: "#/components/responses/Http500ErrorResponse"
        "503":
          $ref: "#/components/responses/Http503ErrorResponse"
        "504":
          $ref: "#/components/responses/Http504ErrorResponse"
components:
  parameters:
    CorrelationId:
      name: X-Correlation-Id
      in: header
      description: Correlation identifier for the request
      required: false
      style: simple
      explode: false
      schema:
        $ref: "#/components/schemas/XCorrelationIdType"
      examples:
        As generated by client:
          value: ef199b05-d1ff-4a2b-b5ef-2bb3ab3f0820
        As generated by API GW:
          value: ef199b05-d1ff-4a2b-b5ef-2bb3ab3f0820#23
  schemas:
    SubscriptionRequestBody:
      required:
        - data
      type: object
      properties:
        data:
          $ref: "#/components/schemas/SubscriptionRequestBodyData"
      description: List of securities (identified by ISIN) a business partner is
        subscribed to for the bulk service.
      example:
        data:
          type: Subscription
          attributes:
            subscription:
              - US0378331005
              - US5949181045
    XCorrelationIdType:
      pattern: ^[0-9A-Fa-f]{8}-?[0-9A-Fa-f]{4}-?4[0-9A-Fa-f]{3}-?[89ABab][0-9A-Fa-f]{3}-?[0-9A-Fa-f]{12}(#[1-9][0-9]*)?$
      type: string
      description: Value of the correlation ID for the server, i.e., a UUID v4 (with
        or without the dash to separate the blocks), optionally followed by a
        '#' and a positive integer.
    SubscriptionRequestBodyData:
      required:
        - attributes
        - type
      type: object
      properties:
        type:
          maxLength: 255
          minLength: 1
          type: string
          description: Type of the resource.
        attributes:
          $ref: "#/components/schemas/ResourceSubscriptionAttributes"
      description: List of securities (identified by ISIN) a business partner is
        subscribed to for the bulk service.
      example:
        type: Subscription
        attributes:
          subscription:
            - US0378331005
            - US5949181045
    Error400:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          description: A human-readable explanation specific to this error.
          example: Unauthorized
        errorDetail:
          description: Additional information about the error.
          allOf:
            - $ref: "#/components/schemas/ErrorDetail400"
      description: Description of a 400 error to help remediation.
    Error:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          description: A human-readable explanation specific to this error.
          example: Unauthorized
        errorDetail:
          description: Additional information about the error.
          allOf:
            - $ref: "#/components/schemas/ErrorDetail"
      description: Description of an error to help remediation.
    ApiGwError:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          description: A human-readable explanation specific to this error.
          example: Unauthorized
      description: Description of an error as provided by the API GW to help remediation.
    ResourceSubscriptionAttributes:
      required:
        - subscription
      type: object
      properties:
        subscription:
          $ref: "#/components/schemas/Subscription"
      description: A subscription (i.e., list of ISINs) for a business partner as a
        resource.
    ErrorDetail400:
      type: object
      description: Detailed description of a 400 error to help remediation. It extends
        RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807) with missing
        and invalid parameters information.
      allOf:
        - $ref: "#/components/schemas/ErrorDetail"
        - properties:
            invalidParams:
              minItems: 1
              type: array
              description: List of parameters with invalid values.
              items:
                $ref: "#/components/schemas/InvalidParameter"
            missingParams:
              minItems: 1
              type: array
              description: List of missing parameters.
              items:
                $ref: "#/components/schemas/MissingParameter"
    ErrorDetail:
      required:
        - status
      type: object
      properties:
        type:
          type: string
          description: >-
            A URI reference (RFC3986) that describes the problem type (in the
            context of the provided API).


            Should resolve to a human-readable document.
          format: uri
          default: about:blank
        title:
          type: string
          description: A short, human-readable summary of the problem type in English.
          example: Not Found
        status:
          maximum: 599
          minimum: 100
          type: integer
          description: The HTTP status code (RFC7231, Section 6) generated by the origin
            server for this occurrence of the problem.
          format: int32
          example: 400
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the
            problem.
          example: ISIN 'US012071998' does not exist.
        instance:
          type: string
          description: A URI reference (RFC3986) that identifies the specific occurrence
            of the problem. It may or may not yield further information if
            dereferenced.
          format: uri
          example: https://www.example.com/books/1234
      description: Detailed description of an error to help remediation. It follows
        RFC 7807 (https://datatracker.ietf.org/doc/html/rfc7807).
    Subscription:
      maxItems: 400000
      type: array
      description: List of securities (identified by ISIN) a business partner is
        subscribed to for the bulk service.
      example:
        - US0378331005
        - US5949181045
      items:
        $ref: "#/components/schemas/Isin"
    InvalidParameter:
      required:
        - in
        - name
        - value
      type: object
      properties:
        in:
          description: Location of the invalid parameter.
          allOf:
            - $ref: "#/components/schemas/ParameterLocation"
        name:
          type: string
          description: Name of the invalid parameter.
        reason:
          type: string
          description: The reason why the parameter's value is invalid.
        value:
          type: string
          description: The invalid value.
      description: Description of a parameter with invalid value.
    MissingParameter:
      required:
        - in
        - name
      type: object
      properties:
        in:
          description: Location of the missing parameter.
          allOf:
            - $ref: "#/components/schemas/ParameterLocation"
        name:
          type: string
          description: Name of the missing parameter.
        reason:
          type: string
          description: The reason why the parameter's value is missing.
      description: Description of a missing parameter.
    Isin:
      pattern: ^[A-Z]{2}([A-Z0-9]){9}[0-9]$
      type: string
      description: "The ISIN (International Securities Identification Number) uniquely
        identifies a financial instrument. See ISO 6166:2021: Financial services
        — International securities identification number (ISIN)."
      example: CH0038863350
    ParameterLocation:
      type: string
      description: The location of the parameter in question
      enum:
        - BODY
        - PATH
        - QUERY
        - HEADER
  responses:
    Http204NoContent:
      description: No Content
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimit-Limit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimit-Remaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimit-Reset"
      content:
        application/vnd.api+json: {}
    Http400ErrorResponse_BulkSet:
      description: Bad Request
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimit-Limit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimit-Remaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimit-Reset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error400"
          examples:
            400 Bad Request - Invalid content in request body:
              $ref: "#/components/examples/Error400_SubscriptionWithInvalidIsins"
            400 Bad Request - Subscription too big:
              $ref: "#/components/examples/Error400_SubscriptionTooBig"
            400 Bad Request - Invalid header parameter:
              $ref: "#/components/examples/Error400_InvalidHeaderParam"
    Http401ErrorResponse:
      description: Unauthorized
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimit-Limit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimit-Remaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimit-Reset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            401 Unauthorized - no certificate provided:
              value:
                message: No required TLS certificate was sent
            401 Unauthorized - invalid certificate (no trust in certificate):
              value:
                message: TLS certificate failed verification
            401 Unauthorized - not authorized (wrong client credentials):
              value:
                message: Unauthorized
    Http403ErrorResponse:
      description: Forbidden
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimit-Limit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimit-Remaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimit-Reset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            403 Forbidden:
              value:
                message: Forbidden
    Http413ErrorResponse:
      description: Content Too Large
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimit-Limit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimit-Remaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimit-Reset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiGwError"
          examples:
            413 Content Too Large:
              value:
                message: Request size limit exceeded
    Http429ErrorResponse:
      description: Too Many Requests
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
        RateLimit-Limit:
          $ref: "#/components/headers/RateLimit-Limit"
        RateLimit-Remaining:
          $ref: "#/components/headers/RateLimit-Remaining"
        RateLimit-Reset:
          $ref: "#/components/headers/RateLimit-Reset"
        Retry-After:
          $ref: "#/components/headers/Retry-After"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiGwError"
          examples:
            429 Too Many Requests:
              value:
                message: API rate limit exceeded
    Http500ErrorResponse:
      description: Internal Server Error
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            500 Internal Server Error:
              value:
                message: Server error
                errorDetail:
                  title: Internal Server Error
                  status: 500
                  detail: Something went wrong.
    Http503ErrorResponse:
      description: Service Unavailable
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiGwError"
          examples:
            503 Service Unavailable:
              value:
                message: unavailable
    Http504ErrorResponse:
      description: Gateway Timeout
      headers:
        X-Correlation-Id:
          $ref: "#/components/headers/X-Correlation-Id"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiGwError"
          examples:
            504 Service Unavailable:
              value:
                message: The upstream server is timing out.
  headers:
    X-Correlation-Id:
      description: Correlation identifier of the original request.
      style: simple
      explode: false
      schema:
        $ref: "#/components/schemas/XCorrelationIdType"
      examples:
        As generated by client:
          value: ef199b05-d1ff-4a2b-b5ef-2bb3ab3f0820
        As generated by API GW:
          value: ef199b05-d1ff-4a2b-b5ef-2bb3ab3f0820#23
    RateLimit-Limit:
      description: >-
        Provides the the requests quota in the time window (i.e., the maximal
        number of acceptable requests for the client within the time window).

        See the 'RateLimit Header Fields for HTTP'
        (https://datatracker.ietf.org/doc/html/draft-polli-ratelimit-headers-01)
        for more information.
      style: simple
      explode: false
      schema:
        minimum: 0
        type: integer
      example: 10
    RateLimit-Remaining:
      description: >-
        Provides the remaining requests quota in the current time window (for
        the specific client).

        See the 'RateLimit Header Fields for HTTP'
        (https://datatracker.ietf.org/doc/html/draft-polli-ratelimit-headers-01)
        for more information.
      style: simple
      explode: false
      schema:
        minimum: 0
        type: integer
      example: 1
    RateLimit-Reset:
      description: >-
        Indicates the number of seconds until the quota resets.

        See the 'RateLimit Header Fields for HTTP'
        (https://datatracker.ietf.org/doc/html/draft-polli-ratelimit-headers-01)
        for more information.
      style: simple
      explode: false
      schema:
        minimum: 0
        type: integer
      example: 50
    Retry-After:
      description: >-
        Indicates the number of seconds the client ought to wait before making a
        follow-up request.

        See RFC7231, §7.1.3
        (https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3).

        *Note: might be higher than 'RateLimit-Reset'.*
      style: simple
      explode: false
      schema:
        minimum: 0
        type: integer
      example: 50
  examples:
    Error400_SubscriptionWithInvalidIsins:
      value:
        message: Validation failed
        errorDetail:
          title: Bad Request
          status: 400
          detail: "Subscription request contains the following invalid ISIN(s):
            'DE000SD4J14', 'CH104032437', 'CH055341828'."
    Error400_SubscriptionTooBig:
      value:
        message: Validation failed
        errorDetail:
          title: Bad Request
          status: 400
          detail: Subscription is limited to 400'000 financial instruments, cannot set it
            larger.
    Error400_InvalidHeaderParam:
      value:
        message: 'header "X-Correlation-ID" validation failed with error: "failed to
          match pattern
          "^[0-9A-Fa-f]{8}-?[0-9A-Fa-f]{4}-?4[0-9A-Fa-f]{3}-?[89ABab][0-9A-Fa-f]{3}-?[0-9A-Fa-f]{12}"
          with ""'
```