Sikoia Data Sources API

openapi: 3.0.1
info:
  title: Sikoia Adverse Media Data Sources API
  termsOfService: https://sikoia.com/About/Terms
  version: '1.0'
servers:
- url: https://api.sikoia.com
  description: API (Production)
- url: https://oauth2.sikoia.com
  description: Authorization Server (Production)
- url: https://api-staging.sikoia.com
  description: API (Staging)
- url: https://oauth2-staging.sikoia.com
  description: Authorization Server (Staging)
security:
- authorizationHeader: []
- apiKeyHeader: []
tags:
- name: Data Sources
paths:
  /v2/{entity_type}/{entity_id}/insight-data-sources:
    get:
      tags:
      - Data Sources
      summary: List data sources for an entity
      description: "### Returns a list of all data sources for an entity.\r\nProvides a list of all data sources attached to an entity which might be used to generate Sikoia Insights and their status. Possible statuses include: Provided, Pending, Complete, Failed.\r\nOnly data sources with a status of 'Complete' will be used to generate Affordability Insights or Income & Employer Verifications."
      operationId: GET_v2-entity_type-entity_id-insight-data-sources
      parameters:
      - name: entity_type
        in: path
        description: Type of entity to find all related data sources for
        required: true
        schema:
          $ref: '#/components/schemas/SikoiaSharedModels.Global.Enums.PathEntityTypeEnum'
      - name: entity_id
        in: path
        description: ID of entity to find all related data sources for
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Insight Data Sources
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SikoiaSharedModels.Global.DataSources.Insight'
              example:
                entity_id: 181eba57-b6b4-4288-8c97-f8299530f071
                entity_type: case
                data_sources:
                - source_name: Stmt - current - Feb 2023 - J Smith and J Hayley
                  source_id: 4b9ac393-d34b-4a14-9ee3-88ce2d244e90
                  data_source_id: 01951375-a680-77ce-b196-44d1feedc47c
                  source_category_type: Document
                  source_type: None
                  status: Provided
                  message: Some message explaining what's happened
                  recipient: Jane Smith
                  source_date: '2023-02-01'
                  source_uris: '["https://api.sikoia.com/v2/documents/4b9ac393-d34b-4a14-9ee3-88ce2d244e90"]'
                  start_date: '2023-02-01'
                  end_date: '2023-03-01'
                  provided_date: '2023-02-10T10:59:46.0000000+00:00'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SikoiaCore.Common.SikoiaErrorResponse'
              example:
                type: InvalidToken
                status: 401
                title: Invalid Token
                detail: Invalid token
                correlation_id: 1c2ae529-318c-4286-b47a-d654597159b5
        '404':
          description: Entity Not Found or Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SikoiaCore.Common.SikoiaErrorResponse'
              example:
                type: ResourceNotFound
                status: 404
                title: Resource Not Found
                detail: No resources found with id b09d7075-7a9a-4528-9937-433a8935761f.
                correlation_id: 6b47bc4d-0944-4d5c-80ef-28b37174bc27
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SikoiaCore.Common.SikoiaErrorResponse'
              example:
                type: RateLimit
                status: 429
                title: Too Many Requests
                detail: You've exceeded the maximum API request limit per minute. Please try again later.
                correlation_id: b6efbb23-ebd3-4195-b627-5feffb9d592f
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SikoiaCore.Common.SikoiaErrorResponse'
              example:
                type: string
                status: 0
                title: string
                detail: string
                correlation_id: string
components:
  schemas:
    SikoiaSharedModels.Global.Enums.PathEntityTypeEnum:
      enum:
      - Companies
      - Persons
      - Cases
      type: string
    SikoiaSharedModels.Global.DataSources.DataSource:
      title: Data Source
      type: object
      properties:
        source_name:
          type: string
          description: An optional field containing the name of the data source, such as a file name (e.g. a payslip). If the source has no name (e.g. an open banking connection), this field is null.
          nullable: true
          readOnly: true
          example: Stmt - current - Feb 2023 - J Smith and J Hayley
        source_id:
          type: string
          description: The identifier for the root source of the data, such as a document ID for files (e.g. payslips) or an account connection ID for a successful open banking connection.
          format: uuid
          readOnly: true
          example: 4b9ac393-d34b-4a14-9ee3-88ce2d244e90
        data_source_id:
          type: string
          description: A unique identifier for a specific data source within a document, such as an individual payslip in a multi-payslip file or an individual bank statement in a multi-statement document.
          format: uuid
          readOnly: true
          example: 01951375-a680-77ce-b196-44d1feedc47c
        source_category_type:
          $ref: '#/components/schemas/SikoiaSharedModels.EndUser.IncomeEmployer.Enums.SourceCategoryType'
        source_type:
          $ref: '#/components/schemas/SikoiaSharedModels.Global.DataSources.Enums.DataSourceType'
        status:
          $ref: '#/components/schemas/SikoiaSharedModels.Global.DataSources.Enums.DataSourceStatus'
        message:
          type: string
          description: An optional field providing additional context about the status.
          nullable: true
          readOnly: true
          example: Some message explaining what's happened
        recipient:
          type: string
          description: An optional field populated when the data source includes a named individual, such as the person on a payslip or bank statement.
          nullable: true
          readOnly: true
          example: Jane Smith
        source_date:
          type: string
          description: The date associated with the document's data, such as the tax year date on an SA302 form, the payment date on a payslip, or the issuance date of the document.
          nullable: true
          readOnly: true
          example: '2023-02-01'
        source_uris:
          type: array
          items:
            type: string
          description: One or more URLs that provide access to additional information about the data source, such as a link to retrieve an uploaded bank statement.
          readOnly: true
          example: '["https://api.sikoia.com/v2/documents/4b9ac393-d34b-4a14-9ee3-88ce2d244e90"]'
        start_date:
          type: string
          description: Optional. The starting date, applicable for data sources that span a period, such as a monthly bank statement or an open banking connection.
          nullable: true
          readOnly: true
          example: '2023-02-01'
        end_date:
          type: string
          description: Optional. The ending date, applicable for data sources that span a period, such as a monthly bank statement or an open banking connection.
          nullable: true
          readOnly: true
          example: '2023-03-01'
        provided_date:
          type: string
          description: The date the data source (e.g. a document) was originally uploaded or created.
          format: date-time
          readOnly: true
          example: '2023-02-10T10:59:46.0000000+00:00'
      additionalProperties: false
    SikoiaCore.Common.SikoiaErrorResponse:
      title: Error Response
      type: object
      properties:
        type:
          type: string
          description: The error type
          readOnly: true
        status:
          type: integer
          description: HTTP status code of the error
          format: HttpCode
          readOnly: true
        title:
          type: string
          description: A short description of the error
          readOnly: true
        detail:
          type: string
          description: More details about what went wrong
          readOnly: true
        correlation_id:
          type: string
          description: Correlation ID, please include this in any support tickets raised
          readOnly: true
      additionalProperties: false
      description: 'See the [Response Guide](https://docs.sikoia.com/docs/api-behaviour#responses) for more detail '
    SikoiaSharedModels.Global.DataSources.Enums.DataSourceStatus:
      title: Data Source Statuses
      enum:
      - Provided
      - Pending
      - Complete
      - Failed
      - Excluded
      type: string
      description: Indicates the current state of the data source e.g. is it still being processed, has a failure been encountered etc
    SikoiaSharedModels.EndUser.IncomeEmployer.Enums.SourceCategoryType:
      title: Source Category Types
      enum:
      - Document
      - OpenBanking
      type: string
      description: The name of the base source of data e.g. a document or open banking
    SikoiaSharedModels.Global.DataSources.Insight:
      title: Insight
      type: object
      properties:
        entity_id:
          type: string
          description: The `company_id`, `person_id` or `case_id` of the entity
          format: uuid
          readOnly: true
          example: 181eba57-b6b4-4288-8c97-f8299530f071
        entity_type:
          enum:
          - company
          - person
          - case
          type: string
          description: The type of the entity
          readOnly: true
          example: case
        data_sources:
          type: array
          items:
            $ref: '#/components/schemas/SikoiaSharedModels.Global.DataSources.DataSource'
          description: All available data sources for a given entity
          readOnly: true
      additionalProperties: false
    SikoiaSharedModels.Global.DataSources.Enums.DataSourceType:
      title: Data Source Types
      enum:
      - None
      - BankStatement
      - Payslip
      - Identity
      - Contract
      - FactFind
      - Other
      - CompanyRegistration
      - StakeholdersDisclosure
      - UtilityBill
      - CreditReport
      - SavingsStatement
      - SA302
      - TaxOverview
      - P45
      - P60
      - EmploymentLetter
      - EmploymentContract
      - ChildBenefitLetter
      - BenefitAwardLetter
      - StudentLoanLetter
      - PensionStatement
      - FinancialAccounts
      - OpenBankingConnection
      - BankAccount
      type: string
      description: The specific type of data that was identified such as a Payslip or SA302 or Bank Account
  securitySchemes:
    authorizationHeader:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyHeader:
      type: apiKey
      name: apikey
      in: header