Codat Supplemental data API

openapi: 3.2.0
info:
  title: Platform Supplemental data API
  version: 3.0.0
  summary: Platform API
  description: "An API for the common components of all of Codat's products.\n\nThese end points cover creating and managing your companies, data connections, and integrations.\n\n[Read about the building blocks of Codat...](https://docs.codat.io/core-concepts/companies) | [See our OpenAPI spec](https://github.com/codatio/oas) \n\n---\n<!-- Start Codat Tags Table -->\n## Endpoints\n\n| Endpoints | Description |\n| :- |:- |\n| Companies | Create and manage your SMB users' companies. |\n| Connections | Create new and manage existing data connections for a company. |\n| Connection management | Configure connection management UI and retrieve access tokens for authentication. |\n| Webhooks | Create and manage webhooks that listen to Codat's events. |\n| Integrations | Get a list of integrations supported by Codat and their logos. |\n| Refresh data | Initiate data refreshes, view pull status and history. |\n| Settings | Manage company profile configuration, sync settings, and API keys. |\n| Push data | Initiate and monitor Create, Update, and Delete operations. |\n| Supplemental data | Configure and pull additional data you can include in Codat's standard data types. |\n| Custom data type | Configure and pull additional data types that are not included in Codat's standardized data model. |\n<!-- End Codat Tags Table -->"
  contact:
    name: Codat
    email: support@codat.io
  termsOfService: https://www.codat.io/legals/
servers:
- description: Production
  url: https://api.codat.io
security:
- auth_header: []
tags:
- name: Supplemental data
  description: Configure and pull additional data you can include in Codat's standard data types.
paths:
  /integrations/{platformKey}/dataTypes/{dataType}/supplementalDataConfig:
    parameters:
    - $ref: '#/components/parameters/platformKey'
    - name: dataType
      in: path
      required: true
      description: Supported supplemental data data type.
      schema:
        x-internal: true
        type: string
        description: Data types that support supplemental data
        enum:
        - chartOfAccounts
        - bills
        - company
        - creditNotes
        - customers
        - invoices
        - items
        - journalEntries
        - suppliers
        - taxRates
        - commerce-companyInfo
        - commerce-customers
        - commerce-disputes
        - commerce-locations
        - commerce-orders
        - commerce-payments
        - commerce-paymentMethods
        - commerce-products
        - commerce-productCategories
        - commerce-taxComponents
        - commerce-transactions
        example: invoices
    put:
      summary: Configure
      description: 'The *Configure* endpoint allows you to maintain or change configuration required to return supplemental data for each integration and data type combination.


        [Supplemental data](https://docs.codat.io/using-the-api/supplemental-data/overview) is additional data you can include in Codat''s standard data types.


        **Integration-specific behavior**

        See the *examples* for integration-specific frequently requested properties.'
      operationId: configure-supplemental-data
      x-speakeasy-name-override: configure
      tags:
      - Supplemental data
      responses:
        '200':
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Payment-Required'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/Not-Found'
        '429':
          $ref: '#/components/responses/Too-Many-Requests'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
        '503':
          $ref: '#/components/responses/Service-Unavailable'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SupplementalDataConfiguration'
            examples:
              Xero - Accounts:
                value:
                  yourKeyNameForAccounts:
                    dataSource: /Accounts
                    pullData:
                      yourNameForTaxType: TaxType
                      yourNameForSystemAccount: SystemAccount
              Xero - Invoices:
                value:
                  yourKeyNameForInvoices:
                    dataSource: /Invoices
                    pullData:
                      yourNameForExpectedPaymentDate: ExpectedPaymentDate
                      yourNameForHasAttachments: HasAttachments
              Xero - Items:
                value:
                  yourKeyNameForItems:
                    dataSource: /Items
                    pullData:
                      yourNameForQuantityOnHand: QuantityOnHand
                      yourNameForTotalCostPool: TotalCostPool
              Xero - Contacts:
                value:
                  yourKeyNameForContacts:
                    dataSource: /Contacts
                    pullData:
                      yourNameForBankAccounts: BankAccountDetails
              Xero - Tax rates:
                value:
                  yourKeyNameForTaxRates:
                    dataSource: /TaxRates
                    pullData:
                      yourNameForCanApplyToLiabilities: CanApplyToLiabilities
                      yourNameForCanApplyToAssets: CanApplyToAssets
                      yourNameForCanApplyToEquity: CanApplyToEquity
                      yourNameForCanApplyToExpenses: CanApplyToExpenses
                      yourNameForCanApplyToRevenue: CanApplyToRevenue
              QBO - Customers:
                value:
                  yourKeyNameForCustomers:
                    dataSource: /Customer
                    pullData:
                      yourNameForSalesTermRef: SalesTermRef.value
                      yourNameForParentRef: ParentRef.value
              QBO - Invoices:
                value:
                  yourKeyNameForInvoices:
                    dataSource: /Invoice
                    pullData:
                      yourNameForSalesTermRef: SalesTermRef.value
        description: The configuration for the specified platform and data type.
    get:
      summary: Get configuration
      description: 'The *Get configuration* endpoint returns supplemental data configuration previously created for each integration and data type combination.


        [Supplemental data](https://docs.codat.io/using-the-api/supplemental-data/overview) is additional data you can include in Codat''s standard data types.'
      operationId: get-supplemental-data-configuration
      x-speakeasy-name-override: get-configuration
      tags:
      - Supplemental data
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SupplementalDataConfiguration'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/Payment-Required'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/Not-Found'
        '429':
          $ref: '#/components/responses/Too-Many-Requests'
        '500':
          $ref: '#/components/responses/Internal-Server-Error'
        '503':
          $ref: '#/components/responses/Service-Unavailable'
components:
  responses:
    Forbidden:
      description: You are using an outdated API key or a key not associated with that resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 403
                service: PublicApi
                error: You are using an outdated API key or a key not associated with that resource.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Payment-Required:
      description: 'An account limit has been exceeded. The type of limit is described in the error property:


        - You have exceeded the 50-company limit that applies to a Free plan. Delete any companies you no longer need and retry the request.

        - The requested sync schedule is not allowed. You requested an hourly sync schedule but this functionality is not included in the Free plan.

        - Your Free account is older than 365 days and has expired. Contact support@codat.io.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 429
                service: PublicApi
                error: You have exceeded the 50-company limit that applies to a Free plan. We recommend that you delete any companies you no longer need and retry the request.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Too-Many-Requests:
      description: Too many requests were made in a given amount of time. Wait a short period and then try again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 429
                service: PublicApi
                error: You have made too many requests in a given amount of time; please retry later.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Internal-Server-Error:
      description: There is a problem with our server. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 500
                service: PublicApi
                error: There is a problem with our server. Please try again later.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Unauthorized:
      description: Your API request was not properly authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Unauthorized:
              value:
                statusCode: 401
                service: PublicApi
                error: Unauthorized
                correlationId: 7eb40d6b415d7bcd99ce658268284056
                canBeRetried: Unknown
                detailedErrorCode: 0
    Service-Unavailable:
      description: The Codat API is temporarily offline for maintenance. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Conflict:
              value:
                statusCode: 500
                service: PublicApi
                error: The Codat API is temporarily offline for maintenance. Please try again later.
                correlationId: bc997528a9d7abb9161ef45f05d38599
                canBeRetried: Unknown
                detailedErrorCode: 0
    Not-Found:
      description: 'One or more of the resources you referenced could not be found.

        This might be because your company or data connection id is wrong, or was already deleted.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorMessage'
          examples:
            Data connection not found:
              value:
                statusCode: 404
                service: PublicApi
                error: Data connection a22dd66b-564a-4832-9b37-7b3ce4aeb7de not found
                correlationId: 8fa2b5f4794970a4ee73758f612e8df0
                canBeRetried: Unknown
                detailedErrorCode: 0
            Company not found:
              value:
                statusCode: 404
                service: ClientsApi
                error: No company was found with ID 846ed55c-974b-4392-a1f1-87b6fdbf3c5e
                correlationId: 0a40c2f31fc8f992fb88b0853e4166f3
                canBeRetried: Unknown
                detailedErrorCode: 0
            No data available:
              value:
                statusCode: 404
                service: PublicApi
                error: No data available for accounts for ID e5889b459f544926ac5b8e6756df2s
                correlationId: 0a40c2f31fc8f992fb88b0853e4166f3
                canBeRetried: Unknown
                detailedErrorCode: 0
  schemas:
    ErrorMessage:
      title: Error message
      type: object
      x-internal: true
      properties:
        statusCode:
          type: integer
          description: The HTTP status code returned by the error.
        service:
          type: string
          description: Codat's service the returned the error.
        error:
          type: string
          description: A brief description of the error.
        correlationId:
          type: string
          description: Unique identifier used to propagate to all downstream services and determine the source of the error.
        validation:
          $ref: '#/components/schemas/ErrorMessage/definitions/errorValidation'
        canBeRetried:
          type: string
          description: '`True` if the error occurred transiently and can be retried.'
        detailedErrorCode:
          type: integer
          description: Machine readable error code used to automate processes based on the code returned.
      definitions:
        errorValidation:
          title: Validation error
          type: object
          nullable: true
          description: A human-readable object describing validation decisions Codat has made. If an operation has failed because of validation errors, they will be detailed here.
          properties:
            errors:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
            warnings:
              type: array
              nullable: true
              items:
                $ref: '#/components/schemas/ErrorMessage/definitions/errorValidationItem'
        errorValidationItem:
          title: Validation error item
          type: object
          properties:
            itemId:
              type: string
              nullable: true
              description: Unique identifier for a validation item.
            message:
              type: string
              nullable: true
              description: A message outlining validation item's issue.
            validatorName:
              type: string
              nullable: true
              description: Name of validator.
    SupplementalDataConfiguration:
      description: ''
      title: Supplemental data configuration
      type: object
      properties:
        supplementalDataConfig:
          type: object
          additionalProperties:
            type: object
            title: Supplemental data source configuration
            description: The client's defined name for the object.
            properties:
              dataSource:
                type: string
                description: 'The underlying endpoint of the source system which the configuration is targeting. '
              pullData:
                type: object
                description: The additional properties that are required when pulling records.
                additionalProperties:
                  type: string
                  description: The client's defined name for the property with the value being the source system's property name which the mapping is targeting.
              pushData:
                type: object
                description: The additional properties that are required to create and/or update records.
                additionalProperties:
                  type: string
                  description: The client's defined name for the property with the value being the source system's property name which the mapping is targeting.
      examples:
      - supplementalDataConfig:
          orders-supplemental-data:
            dataSource: /orders
            pullData:
              orderNumber: order_num
            pushData:
              orderNumber: order_num
  parameters:
    platformKey:
      name: platformKey
      in: path
      required: true
      schema:
        type: string
        minLength: 4
        maxLength: 4
        pattern: '[a-z]{4}'
        example: gbol
        description: A unique 4-letter key to represent a platform in each integration. View [accounting](https://docs.codat.io/integrations/accounting/overview#platform-keys), [banking](https://docs.codat.io/integrations/banking/overview#platform-keys), and [commerce](https://docs.codat.io/integrations/commerce/overview#platform-keys) platform keys.
      description: A unique 4-letter key to represent a platform in each integration.
  securitySchemes:
    auth_header:
      name: Authorization
      description: The word "Basic" followed by a space and your API key. [API keys](https://docs.codat.io/platform-api#/schemas/ApiKeyDetails) are tokens used to control access to the API. You can get an API key via [the Codat Portal](https://app.codat.io/developers/api-keys), via [the API](https://docs.codat.io/platform-api#/operations/list-api-keys), or [read more](https://docs.codat.io/using-the-api/authentication) about authentication at Codat.
      type: apiKey
      in: header
      x-speakeasy-example: Basic BASE_64_ENCODED(API_KEY)
x-stoplight:
  id: 466k6ayziv9at
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 408
  - 429
  - 5XX
  retryConnectionErrors: true
x-speakeasy-name-override:
- operationId: ^list-.*?
  methodNameOverride: list
- operationId: ^list-.*?-attachments
  methodNameOverride: list-attachments
- operationId: ^get-.*?
  methodNameOverride: get
- operationId: ^get-create-.*?-model
  methodNameOverride: get-create-model
- operationId: ^get-create-update.*?-model
  methodNameOverride: get-create-update-model
- operationId: ^get-.*?-attachment
  methodNameOverride: get-attachment
- operationId: ^update-.*?
  methodNameOverride: update
- operationId: ^create-.*?
  methodNameOverride: create
- operationId: ^delete-.*?
  methodNameOverride: delete
- operationId: ^delete-.*?-attachment
  methodNameOverride: delete-attachment
- operationId: ^download-.*?-attachment
  methodNameOverride: download-attachment
- operationId: ^upload-.*?-attachment
  methodNameOverride: upload-attachment
x-codat-docs-path: platform-api
x-codat-keep-docs-paths-local: true
x-codat-speakeasy-pagination:
  type: offsetLimit
  inputs:
  - name: page
    in: parameters
    type: page
  outputs:
    results: $.results