Codat.Platform.SupplementalData (codat v1.0.0)

Copy Markdown View Source

Configure supplemental data — extra fields pulled from an integration and merged into standard Codat data type responses.

Supplemental data allows you to capture integration-specific fields that Codat doesn't expose by default (e.g., custom fields in QuickBooks, extra metadata in Xero) and have them returned alongside the standard fields.

How It Works

  1. Configure a supplemental data property for a data type + integration pair
  2. When Codat syncs that data type, it pulls the extra fields from the integration
  3. The extra fields appear in supplementalData.content on each record

Example

# Configure supplemental data for invoices in QuickBooks Online
{:ok, _} = Codat.Platform.SupplementalData.configure(client,
  "invoices",    # Codat data type
  "gbol",        # Integration key (QuickBooks Online)
  %{
    supplementalDataConfig: %{
      "CustomField1" => %{
        dataType: "invoices",
        pullData: %{
          "invoices" => "CustomField1.DefinitionId"   # Path in QBO API
        }
      }
    }
  }
)

# Now GET /companies/{id}/data/invoices will include:
# %{
#   "id" => "inv-1",
#   ...standard fields...
#   "supplementalData" => %{
#     "content" => %{"CustomField1" => "value"}
#   }
# }

Summary

Functions

configure(client_or_data_type, data_type_or_integration, integration_or_body, body_or_opts \\ %{})

Sets the supplemental data configuration for a data type + integration pair.

get_config(client_or_data_type, data_type_or_integration, integration_or_opts \\ [])

Returns the supplemental data configuration for a data type and integration.

Functions

configure(client_or_data_type, data_type_or_integration, integration_or_body, body_or_opts \\ %{})

@spec configure(
  Codat.Client.t() | String.t(),
  String.t(),
  String.t() | map(),
  map() | keyword()
) :: {:ok, map()} | {:error, Codat.Error.t()}

Sets the supplemental data configuration for a data type + integration pair.

Parameters

  • data_type — Codat data type, e.g. "invoices", "bills", "customers"
  • integration_key — integration platform key, e.g. "gbol" (QuickBooks Online)
  • body — configuration body (see module docs for shape)

Example

{:ok, _} = Codat.Platform.SupplementalData.configure(client,
  "invoices", "gbol",
  %{
    supplementalDataConfig: %{
      "PONumber" => %{
        dataType: "invoices",
        pullData: %{"invoices" => "PONumber"}
      }
    }
  }
)

get_config(client_or_data_type, data_type_or_integration, integration_or_opts \\ [])

@spec get_config(Codat.Client.t() | String.t(), String.t(), String.t() | keyword()) ::
  {:ok, map()} | {:error, Codat.Error.t()}

Returns the supplemental data configuration for a data type and integration.

Example

{:ok, config} = Codat.Platform.SupplementalData.get_config(
  client, "invoices", "gbol"
)