openapi: 3.2.0
info:
  version: 1.3.0
  title: Data Recipient Registration Recipients API
  description: Truist Financial, following FDX V5.4.1 Recipient API
  contact:
    name: Truist API Support
    url: https://developer.truist.com/contact-us
servers:
- url: https://api-sandbox.truist.com/retail
  description: Truist Financial Retail Open Banking APIs - Sandbox environment
- url: https://apicert-secure.truist.com/retail
  description: Truist Financial Retail Open Banking APIs - Certification environment
- url: https://api-secure.truist.com/retail
  description: Truist Financial Retail Open Banking APIs - Production environment
security:
- BasicAuth: []
tags:
- name: Recipients
  description: Manage recipients
paths:
  /v1/register:
    parameters:
    - $ref: '#/components/parameters/FapiInteractionIdHeader'
    post:
      summary: Recipient Registration Request
      description: Request to Register Recipient by Creating a Recipient Record
      operationId: createRecipient
      tags:
      - Recipients
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientRequest'
            examples:
              Create Recipient Record at Provider:
                value:
                  client_name: My Example Client
                  description: Recipient application for specified financial use case
                  redirect_uris:
                  - https://partner.example.net/callback
                  logo_uri: https://client.example.org/logo.png
                  auto_connect: true
                  client_uri: https://example.net/
                  contacts:
                  - support@example.net
                  - https://example.net/contact-us
                  scope: ACCOUNT_DETAILED TRANSACTIONS
                  duration_type:
                  - TIME_BOUND
                  duration_period: 365
                  lookback_period: 180
                  intermediaries:
                  - name: Data Access Platform Name
                    description: Company servicing permissioned financial data sharing
                    uri: https://partner.example/
                    logo_uri: https://partner.example/logo.png
                    contacts:
                    - support@dap-partner.com
                    - https://dap-partner.com/contact-us
                  - name: Digital Service Provider Name
                    description: Digital Service Provider to the Recipient
                    uri: https://sub-partner-one.example/
                    logo_uri: https://sub-partner-one.example/logo.png
                    contacts:
                    - support@sub-partner-one.com
                    - https://sub-partner-one.com/contact-us
      responses:
        '201':
          description: Created
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
          content:
            text/plain:
              schema:
                type: string
              examples:
                Provider Response With Full Record Of Recipient:
                  value: eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg
        '202':
          description: Accepted
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
          content:
            text/plain:
              schema:
                type: string
              examples:
                Accepted DR registration still pending its Payment Networks setup:
                  value: eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg
                Accepted DR registration still pending authorization server setup:
                  value: eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg
        '400':
          description: Bad Request
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                MISSING_REQUIRED_PARAMETER:
                  value:
                    code: '401'
                    message: Following required parameters are missing - {client_name, redirect_uris, client_uri, contacts, scope, duration_type, intermediary name, intermediary uri, intermediary contacts}
                INVALID_CLIENT_METADATA:
                  value:
                    code: '401'
                    message: Following request fields have invalid values - {redirect_uris, logo_uri, client_uri, auto_connect, contacts, scope, duration_type, duration_period, lookback_period, intermediary uri, intermediary logo_uri, contacts}
                OUT_OF_CONTRACT_METADATA:
                  value:
                    code: '401'
                    message: Following request fields have out of contract metadata - {scope, duration_type, duration_period, lookback_period}
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
  /v1/register/{clientId}:
    parameters:
    - $ref: '#/components/parameters/ClientIdPath'
    - $ref: '#/components/parameters/FapiInteractionIdHeader'
    get:
      summary: Get Recipient
      operationId: getRecipient
      tags:
      - Recipients
      description: Get a specific recipient data identified with clientId
      responses:
        '200':
          description: OK
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
          content:
            text/plain:
              schema:
                type: string
              examples:
                Provider Response With Full Record Of Recipient:
                  value: eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
    put:
      summary: Update a Recipient
      operationId: updateRecipient
      tags:
      - Recipients
      description: Update data for a specific recipient identified with clientId
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientRequest'
      responses:
        '200':
          description: OK
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
          content:
            text/plain:
              schema:
                type: string
              examples:
                Updated Provider Response With Full Record Of Recipient:
                  value: eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzcyI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZfV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5NzAKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6qJp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJNqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7TpdQyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoSK5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg
        '400':
          description: Bad Request
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                MISSING_REQUIRED_PARAMETER:
                  value:
                    code: '401'
                    message: Following required parameters are missing - {client_name, redirect_uris, client_uri, contacts, scope, duration_type, intermediary name, intermediary uri, intermediary contacts}
                INVALID_CLIENT_METADATA:
                  value:
                    code: '401'
                    message: Following request fields have invalid values - {redirect_uris, logo_uri, client_uri, auto_connect, contacts, scope, duration_type, duration_period, lookback_period, intermediary uri, intermediary logo_uri, contacts}
                OUT_OF_CONTRACT_METADATA:
                  value:
                    code: '401'
                    message: Following request fields have out of contract metadata - {scope, duration_type, duration_period, lookback_period}
                UPDATE_NOT_YET_IMPLEMENTED:
                  value:
                    code: '401'
                    message: Following requested field updates are not yet supported by Truist - {client_name, auto_connect, duration_type, duration_period}
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '409':
          $ref: '#/components/responses/409'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
    delete:
      summary: Delete Recipient
      operationId: deleteRecipient
      tags:
      - Recipients
      description: Delete data for a specific recipient identified with clientId
      responses:
        '204':
          description: No Content
          headers:
            x-fapi-interaction-id:
              $ref: '#/components/headers/x-fapi-interaction-id'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '405':
          $ref: '#/components/responses/405'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
        '504':
          $ref: '#/components/responses/504'
components:
  responses:
    '401':
      description: Unauthorized
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            INVALID_BASICAUTHENTICATION_SOURCE:
              value:
                code: '603'
                message: Authentication failed
    '429':
      description: Too Many Requests
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            SPIKE_ARREST_VIOLATION:
              value:
                code: '1207'
                message: Traffic spike, too many requests
            QUOTA_VIOLATION:
              value:
                code: '1207'
                message: Quota violation, too many requests
    '500':
      description: Internal Server Error
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            INTERNAL_SERVER_ERROR:
              value:
                code: '500'
                message: System down for maintenance
    '405':
      description: Client called an unimplemented REST method
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            INVALID_METHOD:
              value:
                code: '1206'
                message: Method Not Allowed
    '404':
      description: Not Found
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            RESOURCE_NOT_FOUND:
              value:
                code: 1107-1206
                message: URI does not represent a recognized resource
    '504':
      description: Service Timed out
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            GATEWAY_TIMEOUT:
              value:
                code: '504'
                message: A time-out occurred connecting to an upstream server
    '403':
      description: Forbidden
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            NO_APIPRODUCT_MATCHFOUND:
              value:
                code: '403'
                message: Forbidden, inadequate authorization
    '409':
      description: Conflict
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            DUPLICATE_CLIENT:
              value:
                code: '409'
                message: Duplicate Client Name request
    '503':
      description: Service unavailable / system down for maintenance
      headers:
        x-fapi-interaction-id:
          $ref: '#/components/headers/x-fapi-interaction-id'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            SERVICE_UNAVAILABLE:
              value:
                code: '503'
                message: Scheduled Maintenance
  schemas:
    Intermediary:
      title: Intermediary
      description: Data Access Platform, Service Provider, or any other entity in the data sharing chain between a Data Provider to a Data Recipient. In snake case to match IETF RFC 7591 naming formats
      type: object
      properties:
        name:
          type: string
          description: Name of intermediary party
        description:
          type: string
          description: A short description of the intermediary
        uri:
          type: string
          format: uri
          description: A URL string of a web page providing information about the intermediary
        logo_uri:
          type: string
          format: uri
          description: A URL string that references a logo for this intermediary
        contacts:
          type: array
          items:
            type: string
          description: Array of strings representing ways to contact people responsible for this intermediary
      required:
      - name
      - uri
      - contacts
    Identifier:
      title: Identifier
      description: Value for a unique identifier
      type: string
      maxLength: 256
    ConsentDurationType:
      title: Consent Duration Type
      description: Duration of the Consent Grant, per FDX UX Guidelines v1.0 (pp 18 - 20)
      type: string
      enum:
      - TIME_BOUND
    RecipientRequest:
      title: Recipient Request
      type: object
      description: Used to request a recipient registration. In snake case to match IETF RFC 7591 naming formats
      properties:
        client_name:
          $ref: '#/components/schemas/Identifier'
          description: 'The Data Recipient or Data Recipient Application name displayed by Data Provider during the consent Flow as well as in the Consent Dashboard. Must be unique from all previously registered client names. Truist allows alphanumeric, spaces and these special characters: underscore (_), hyphen (-), period (.), pound sign (#), dollar sign ($), percent (%), ampersand (&) and comma (,). Prior name value must be sent in Truist PUT /register/{id} update call, even though functionality to permit update of name field is still being built.'
        description:
          type: string
          description: A short description of the Data Recipient application. If not sent in an update request the prior value will be cleared
        redirect_uris:
          type: array
          items:
            type: string
          description: An array of eligible Redirect URI targets
        logo_uri:
          type: string
          description: Data Recipient Logo URL location. If not sent in an update request the prior value will be cleared
          format: uri
        auto_connect:
          type: boolean
          description: Flag which provides information whether Data Recipient customers can auto-connect new accounts. Prior auto_connect value, if true, must be sent in Truist PUT /register/{id} update call, even though functionality to permit update of auto_connect field is still being built
        client_uri:
          type: string
          description: The URI which provides additional information about the Data Recipient
          format: uri
        contacts:
          type: array
          items:
            type: string
          description: Array of strings representing ways to contact individuals responsible for the Data Recipient application
        scope:
          type: string
          description: String form field with a list of data clusters. Prior or updated scope value must be sent in Truist PUT /register/{id} update call, Data Recipient scope will be set to the value in PUT request
        duration_type:
          type: array
          items:
            $ref: '#/components/schemas/ConsentDurationType'
          description: The type of consent duration for the Data Recipient consumers. Only value of duration_type which Truist currently supports and accepts is ['TIME_BOUND']
        duration_period:
          type: number
          description: The maximum consent duration in days that can be requested for a Recipient consumer. Maximum value is 365. Prior duration_period value must be sent in Truist PUT /register/{id} update call, even though functionality to permit update of duration_period field is still being built
        lookback_period:
          type: number
          description: The maximum number of days allowed for Data Recipient consumers to obtain in transaction history, effective from the current date. If not sent in an update request the prior value will be left unchanged
        intermediaries:
          type: array
          items:
            $ref: '#/components/schemas/Intermediary'
          description: An array of the intermediaries for this data recipient. If not sent in an update request the prior values will be cleared
      required:
      - client_name
      - redirect_uris
      - client_uri
      - contacts
      - scope
      - duration_type
    FapiInteractionId:
      title: FAPI Interaction ID
      description: Universally unique identifier for this interaction, used across all FDX API requests and responses
      type: string
      format: uuid
      minLength: 36
      maxLength: 36
      example: c770aef3-6784-41f7-8e0e-ff5f97bddb3a
    Error:
      title: Error
      description: An error entity which can be used at the API level for error responses or at the account level to indicate a problem specific to a particular account
      type: object
      properties:
        code:
          type: string
          description: Error code defined by FDX API Specification or Data Provider indicating the error situation which has occurred
        message:
          type: string
          description: End user displayable information which might help the customer diagnose an error
  parameters:
    ClientIdPath:
      name: clientId
      in: path
      description: Client Identifier. Uniquely identifies a Client
      required: true
      schema:
        $ref: '#/components/schemas/Identifier'
      example: uYrD4LD7P9948lzy3UCPHLWljGqcRWx06Tn
    FapiInteractionIdHeader:
      name: x-fapi-interaction-id
      in: header
      description: Unique request identifier
      schema:
        $ref: '#/components/schemas/FapiInteractionId'
      required: true
      example: c770aef3-6784-41f7-8e0e-ff5f97bddb3a
  headers:
    x-fapi-interaction-id:
      description: Unique request identifier
      schema:
        $ref: '#/components/schemas/FapiInteractionId'
      required: true
      example: c770aef3-6784-41f7-8e0e-ff5f97bddb3a
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Base64(client_id:client_secret)