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.
  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 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 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:
  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.
  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
    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
    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
    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
    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
    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
    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
  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
  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