Extended Data

Extended data adds attributes of your own to the standard fields GAINS Connect exchanges with you: for example a region, a cost centre, or the identifier a record carries in your ERP. You can send them with inbound records, and receive them with outbound reads and webhooks.

How extended data is set up

Extended data is configured per environment by your GAINS representative. You cannot create or change it through the API. Before you use it, agree with your GAINS representative on:

• the API label of each attribute: the key it is sent and returned under, for example Region;
• the subject and the level within the payload where it appears, for example a demand transaction's header or its lines;
• for inbound attributes, whether each one is required on every record or optional, and its type and maximum length;
• for outbound attributes, whether each one can be used as a filter on outbound reads.

Until a subject is configured, its inbound endpoint accepts no ExtendedData and its outbound responses carry none.

API labels

The API label is the only name you use for an attribute. On inbound records it is the key inside the ExtendedData object; on outbound records it is the key GAINS returns it under; on outbound reads it is the name of the query parameter that filters by it; in a webhook filter it is written ExtendedData.<ApiLabel>.

Seeing what is configured

Call GET /extended-data to see the configuration of your environment:

• its Inbound section lists, for each payload (DataType), the ApiLabel of every attribute and whether it IsOptional;
• its Outbound section lists, for each payload, the ApiLabel of every attribute and whether it IsAvailableAsQueryParam, that is, whether it can be used as a filter.

When nothing is configured in either direction, it answers 204 with no body.

Sending and receiving

Which subjects accept or return extended data is listed in Inbound Subjects and Outbound Subjects.

Related

• Sending Extended Data
• Receiving Extended Data
• Custom Schema: loading data that fits none of the standard subjects.
• Inbound Subjects
• Outbound Subjects