Documentation

3.1.1. URL

URL authorisation is performed by appending an API key directly to the URL as a parameter.

The following fields are available:

3.1.2. Basic

Basic authentication uses a combination of username and password to access the API.

The following fields are available:

3.1.3. Token

This method uses a token that is sent in the header of the API request.

The following fields are available when String is selected as the token type:

The following fields are available when JWT is selected as the token type:

3.1.4. OAuth2.0

Token Type: Select the data type of the token here (string, JWT, etc.).

OAuth 2.0 is a more complex process that is suitable for APIs with increased security requirements and offers advanced authorisation features.

The following fields are available when "Authorisation Code" is selected as the grant type:

The following fields are available when "Client Credentials" is selected as the grant type:

The following fields are available when "JWT" is selected as the grant type:

The following fields are available when "Password" is selected as the grant type:

The following fields are available when "Refresh Token" is selected as the grant type:

At the provider level, you can also configure "IP ranges" and "error configurations". However, configuring these elements is optional.

3.1.5. IP Ranges

IP ranges serve as IP filters to increase security when integrating third-party systems into Salesforce via integraid. You can specify start and end IP addresses to define a specific range of IP addresses.

X

If a server attempts to access the system using an IP address outside of the defined IP ranges, access is automatically denied. However, multiple IP ranges can be specified, and access is granted if the IP address is in at least one of these ranges. If no IP ranges are defined, access is allowed for all IP addresses by default.

3.1.6. Error Configurations

Error configurations are used for error handling and define which HTTP response codes should be considered errors.

X

In the "Response Code" field, you can either define specific response codes or general code ranges, such as all codes beginning with "4". 400 response codes can, for example, be interpreted as errors or as permissible responses, while 500 codes are always treated as errors.

Note: If you receive an error message saying "Access denied" or something similar with a 500 error, this may be due to the URL. Make sure that "https://" or "http://" is included in the URL. The protocol (http:// or https://) may also need to be added to the provider or to the endpoint if the provider's base URL is empty.

The "Identifier" field can also be used to define the identifier of the node in the response that contains the error message, e.g. "Message" or "Error". This identifier is used to clearly report errors in the results and to the user.

In addition, the "Deactivate Mapping" checkbox can be used to specify whether the error defined in the configuration should cause the mapping to be deactivated if it occurs again.

3.2.1. Types of Endpoints

First, the type of endpoint must be specified. The types determine how communication between Salesforce and third-party systems takes place. They define whether a request is synchronous or asynchronous and how the response is handled. There are four different types:

• Callout: A callout is a synchronous process in which integraid sends a request to a third-party system and receives an immediate response. The transaction is considered complete upon receipt of the response.
• Async callout: An async callout enables asynchronous communication in which a request is sent and a callback URL is specified for the subsequent transmission of the response. The response is sent at a later, unspecified time.
• Callin: Callin enables a third-party system to notify integraid of certain events, similar to a webhook. Notifications can be sent multiple times and at different times without a prior request. HTML forms can also send data to endpoints of this type.
• Forced Async Callout: The forced async callout executes a callout that is synchronous with the interface asynchronously on the Salesforce side. This bypasses Salesforce limits and thus enables longer callouts in Salesforce. We recommend using this type only when Salesforce errors occur due to Salesforce limits being reached.

3.2.2. HTTP Methods

HTTP methods are used to send requests to a server. Each method has a specific function that describes what kind of operation should be performed on a resource. Here is an overview:

• The GET method is used to query data from the interface without changing it. This method always returns the same results for repeated requests as long as the data on the interface side remains unchanged.
• The POST method is used to create new records in Salesforce or to execute actions such as triggers. Repeated requests can result in multiple records being created or processes being executed multiple times.
• The PUT method is used to create or completely update records in Salesforce. With each request, the record in Salesforce is replaced by the transmitted data, ensuring that the result remains consistent.
• The PATCH method is used to update existing records in Salesforce in a targeted manner. Only the specified fields are changed, making this method particularly efficient for incremental updates.
• The DELETE method allows you to delete records in Salesforce. Resending the request has no additional effect, as the record is already removed after the first request.

You can find out which HTTP method is required for your application in the provider's interface documentation.

Then you need to configure the endpoint by clicking on the "Configure" button. Here you configure the structure of outgoing and incoming data (outbound, inbound).

3.2.3. Outbound

First, you determine where the information you want to transfer from your Salesforce system to the interface is located. You have the options "Body", "Header" and "URL". These are the locations where the data can be transferred.

X

Body

If you select "Body" as the attribute, the data to be sent will be transferred in the message body of the HTTP request.

• Content Type: You can specify the format of the message, e.g. application/json, application/xml or other formats, depending on the requirements of the interface.
• Quantity: This determines whether a single data element (single) or multiple elements (array) are to be transferred.
• Type: A distinction is made between node and value:
  • Node: A structure with sub-elements.
  • Value: A single value.

Below the body, you can create individual fields or nested structures that are populated with Salesforce data.

Using the "Import" function, you can also upload a sample structure (e.g. JSON), which will automatically create the fields.

Typical use cases for Body are:

• Sending records to REST APIs (e.g. POST new leads or opportunities).
• Transferring complex JSON objects.

Header

If you select "Header", the Salesforce data is inserted into the HTTP header of the request.

• Quantity: Here, you also define whether individual values or arrays are sent.
• Type: Headers can also be divided into simple key-value pairs (value) or structured nodes.

Headers are used to:

• Send authentication information (e.g. API keys, bearer tokens).
• Transmit special control information to the API (e.g. content type headers).

As with Body, you can also add child elements (fields) here to build dynamic header fields.

URL

If you select "URL", data is appended to the API URL as parameters (query parameters).

• Quantity: Single values (single) or lists (array) are possible.
• Type: Defines whether the parameter is treated as a node or value.

With URL parameters, you can:

• Define static values.
• Dynamically transfer fields from Salesforce to the URL (e.g. domain, ID, status).
• Build arrays as comma-separated parameters.

The URL parameters are automatically formatted correctly (?key1=value1&key2=value2) and appended to the endpoint URL.

Typical use cases for URL parameters are:

• GET requests with filter or search criteria.
• Identification of a resource via the URL.

3.2.4. Inbound

Next, you specify what information you will receive from the interface. The inbound configuration deals with the structure in which the system receives data from an interface. Here you also have the options "Body", "Header" and "URL".

X

Body

If you select "Body", integraid processes the content from the message body of the API response.

• Content Type: You specify the expected format, e.g. application/json, application/xml, etc. This tells integraid how to read the response structure.
• Type: This determines whether the data is interpreted as a node (complex structure) or value (single value).

You can create any number of attributes (data fields) in the body:

• Each attribute is assigned an identifier (name from the API).
• You specify the data type, e.g. string, number, boolean or date.
• You can define the structure yourself or generate it automatically from a sample response using the import function.

Typical use:

• Transferring complex JSON or XML responses with nested elements.
• Extracting multiple data fields (e.g. company name, turnover, location).

Header

If you select "Header", integraid reads the information directly from the HTTP headers of the response.

• Type: Here, too, you can use Node or Value, depending on whether simple or structured data is being processed.

In the configuration, you specify:

• Which header fields are to be evaluated.
• The types of header data (e.g. string, Boolean).

Typical use:

• Processing authentication data or system information transported in the header.
• Reading status information (e.g. tokens, session IDs).

URL

If "URL" is selected, integraid processes parameters or information contained in the URL of the response.

• Type: URL parameters can also be structured as simple values (Value) or complex structures (Node).

Here you define:

• Which URL parameters are to be evaluated (e.g. ID, status).
• How the data is read and further processed.

Typical use:

• APIs that return statuses or IDs via the URL.
• Retrieving results via redirects or query strings.

"Add Body" button

The "Add Body" button allows you to define alternative response bodies. This is particularly important if interfaces return different content types in case of success and failure. For example, a file may be returned as binary data (octet stream) in case of success, while JSON data is delivered in case of failure.

X

By clicking on "Add Body", you can select one of the remaining content types and define a custom response structure. integraid uses the content type provided by the interface to determine the correct direction for response processing.

3.3.1. Scopes

The basis of mapping is the data context, which is defined by so-called "scopes". Scopes are the data sources or ‘data truths’ used for mapping. They can have different levels, such as Field Scopes, List Scopes and Free Scopes, and allow access to the entire data structure in Salesforce.

First, a primary scope is created. This is done using the "Add Scope" button at the top right of the mapping record. It defines under which object the information relevant to the endpoint is located.

X

Here you select the desired object. If, for example, you need data from an account object for a callout, select the account as the primary scope. For example, we have defined the primary scope as Lead. The primary scope is visible in the Scope data record. Further scopes can now be defined from the primary scope. To do this, click on the Scope data record.

X

In addition to the primary scope, you can create so-called field scopes and list scopes within the primary scope by clicking on the "Create Child Scope" button. These are so-called "children" of the primary scope, i.e. they refer to data within the object of the primary scope. By clicking on the "New" button in the scope data record, you can also create a free scope.

X

• Field scopes refer to lookup fields of the object and the data of the objects to which the lookup points (e.g. an account).
• List scopes refer to data from the object's lists (e.g. all contacts under the account defined in the field scope).
• Free scopes refer to all data records in Salesforce and do not need to be linked to a field or list scope (e.g. all products in Salesforce).

The principle of scopes can be confusing at first, which is why we will explain it again later using an example.

3.3.2. Target Objects

In addition to the scopes, target objects can also be created. These are specially designed for inbound mappings and are used to perform specific actions on Salesforce objects. To create a new target object, click on the "New" button next to "Target Objects".

X

An interface for creating a "Target Object" data set opens. Give the Target Object a name, enter the object name and select an action.

X

The following actions are available:

• Insert: New data records are created.
• Read: The data is only read; no changes are made to data records.
• Update: Existing data records are updated.
• Upsert: New data records are inserted or existing ones are updated if a matching data record already exists.

3.3.3. Outbound Mapping

Once you have created your scopes, you can start configuring the mapping. Outbound mapping allows you to specify where the information to be sent to the interface is taken from. You can start the configuration by clicking the "Configure" button within the mapping data set.

X

Select "Outbound" as the direction.

X

The data location specified in the outbound endpoint has already been selected.

X

Now select the scope that contains the relevant information. Click on the "Add" button to add the attribute. Under "Source", you can now access all relevant fields that contain the outgoing information.

X

For handling arrays, there is also the "Map Multiple Values" checkbox, where the values are separated by a character specified in the "Separator" field.

However, you also have the option of filling the attribute statically by leaving the "Scope" field blank. You can then enter your value in "Source".

X

By clicking on the "Pick Variable" button, you also have the option of accessing certain variables that are frequently used dynamically.

X

They can be used to generate dynamic values that can later be adjusted in the field next to them (e.g. timestamp minus one week). It is possible to enter a deviation in minutes to define dynamic date and time values.

3.3.4. Inbound Mapping

Inbound mapping allows you to specify where the data received from the interface should be stored in your Salesforce architecture. You also start the configuration via the "Configure" button within the mapping record, but this time select "Inbound" as the direction.

X

Here, under "Target", select the target object to which the values received from the interface are to be transferred. Under "Attributes", you have access to all attributes that have been defined in the endpoint.

X

By clicking on the "Add" button, you can add the configuration and, in the next step, select the field in which the respective attribute is to be displayed under "Field".

X

Here, too, the "Map multiple values" checkbox allows you to process arrays or comma-separated values. If an attribute contains multiple values, you can use the checkbox to control how these values are written to Salesforce (e.g. all values comma-separated in a text field or in a multiple selection list).

If no attribute is specified, you also have the option of specifying static values or accessing the "Response Code" and "Timestamp" variables.

X

In the "Configure Children" section, you can create records related to a parent object. Set your previously created target object as the "Target" and click "Add".

X

Now you can click on "Configure" and go one level deeper in the configuration. Here, the configuration works exactly as it does at the parent object level. If you want to link your child object to one higher up in the hierarchy, you can leave the attribute blank. The parent object will then appear in the dynamic variables:

X

This allows you to access objects that are several levels above your position. The numbering refers to your current position (#1 = one position above you).

The "Back to Parent Object" button takes you back to the higher level.

X

Note: You can use both merge fields* and merge attributes* to reference data from the parent object or the interface response and write it to the fields of the child object. The system automatically validates whether the merge fields have been entered correctly.

3.3.5. Field Updates

Field updates are a feature in integraid that allows you to update fields in Salesforce after a callout or callin has taken place. Unlike data configurations, which are updated depending on the response from the interface, field updates are always executed regardless of whether the interface was successful, returned an error, or did not respond at all. You can create a new Field Update by clicking the "New" button next to Field Updates within your mapping record.

X

A screen for creating a "Field Update" data record opens.

X

Here you can give the record a name, specify the scope and enter the name of the field to be updated in "Field Name". In "Operator" you can specify the comparison operator to be matched, in "Condition Value" the current value of the target field and in "New Value" the target value for the updated field. The value in "New Value" is only written here if the condition specified in "Operator" is met (e.g., only write to a field if it is empty). In addition, under "Event", you select the events that should trigger the field update.

Once the mapping has been configured, you can validate it by clicking on the "Validate" button and activate it by clicking on the "Activate" button. To test it, you can click on the "Test" button.

X

Here you can select a record within your scopes and click "Create" to create a job.

X

3.3.6. Jobs

Jobs are a central component in integraid that handle every callout and every callin. They serve as a kind of log or record for every interaction with an interface and enable asynchronous processing of data. You can find all your jobs in the tab of the same name on the integraid interface.

X

• When a test job is created from a mapping, the callout is executed, but no data is written to the database. This prevents live data from being affected by test runs.
• If an error occurs during data application, the underlying error can be corrected and the data application can be repeated using the "Retry" button in the job.
• The "Apply" button is used to manually trigger the application of a job. This means that the results of a callout are written to the database. There is then an ‘Evaluate’ option that allows you to view the effect of the application before it is executed.

X

Each job also has a status that indicates whether the job is still open or has been successfully completed. If an error occurs, the job remains open, allowing you to respond to open jobs and rerun them if necessary.

3.4.1. Preparation in Salesforce

• Create fields: In the standard Salesforce lead object, we first create five fields to store the data returned by Abstract API. These fields are:
  • Location
  • Founded (year of foundation)
  • Employees (number of employees)
  • Revenue (annual turnover)
  • Technologies (list of technologies used)
• Create formula field: We also create a formula field that extracts the domain from the website field. Abstract API requires the domain as an identifier for the company.

X

3.4.2. Configuration in integraid

• Create provider:
  • First, we create a new provider record in integraid that defines the interface provider. In this case, we call it "Abstract API". We leave the base URL blank.

X

• Configure authorisation: The second step is to configure authorisation. Set the authorisation type to "URL" and pass the API key from Abstract API as a URL parameter with the name "api_key".

X

• Define endpoint: The third step is to configure the endpoint. This includes the type of data the interface expects and the structure of the returned data. We create an endpoint with the following information:
  • Name: Company Enrichment
  • Provider: Abstract API
  • Type: Callout
  • Method: GET
  • URL: https://companyenrichment.abstractapi.com/v2

We copied the HTTP method (GET) and the URL of the Abstract API from the interface documentation.

X

Configure outbound: In the interface documentation, we can see that the interface expects a URL parameter called "Domain".

X

So we click on the "Configure" button within the endpoint, select "Outbound" and then "URL". We enter "domain" in the Identifier field and select "Value" as the Type.

X

Configure inbound: Here, the structure of the response from Abstract API is defined. In the interface documentation, we see a sample response in JSON format, which we can copy and import into integraid.

X

We click on the "Configure" button within the endpoint again, select "Inbound" and then "Body". We set the content type to "Application JSON" and select "Node" for the type. Now click on "Import" and then copy our sample response into the "Input" field. Clicking on the ‘Import’ button automatically creates the attribute structure.

X

Finally, click on the "Save" button, the attributes are saved and the endpoint is configured.

• Configure mapping: The fourth step is to configure the mapping. We create a new mapping that establishes the connection between the structure in the endpoint and the Salesforce data. We name the mapping and link it to the "Company Enrichment" endpoint.

X

First, we define the scope by clicking on "Add Scope". Here, we select Lead as our primary scope.

X

Configure outbound: The "Domain" attribute is assigned to the formula field that extracts the domain from the website field. To do this, click on "Add" and then select the previously created formula field "Domain__c" under Source.

X

Configure inbound: Here, the fields in the lead object are assigned to the attributes of the Abstract API response. We fill in the fields we created earlier:

• "Annual Revenue" is assigned to the "Revenue" field.
• "Country" is assigned to the "Location" field.
• "Employee Count" is assigned to the "Employees" field.
• "Founded" is assigned to the "Founded" field.
• "Technologies" is assigned to the "Technologies" field. We configure the array values to be written as a comma-separated list in the text field by checking "Map Multiple Values" and entering a comma in "Separator".

X

Finally, we activate the mapping by clicking on the "Activate" button, thereby completing the configuration in integraid.

X

3.4.3. Configuration in Salesforce Flow

First, we create a new record-triggered flow in our Salesforce system. The flow should then be triggered when the website field in the lead object is filled for the first time.

X

We then add an asynchronous path, as no direct callout is permitted after a data change (update/insert) in Salesforce.

X

Now we need to create a variable by opening the Toolbox* at the top left of the Flow Builder and clicking on "New Resource". Here we create the following variable:

• Resource Type: Variable
• API Name: Ids
• Data Type: Text
• Allow multiple values: checked

X

Next, we add an Assignment element in which the resource named "IDs" is populated with the ID of the lead that triggers the logic.

X

Now let's add an integraid callout. The mapping ID created earlier is passed as a parameter, and the "IDs" variable is passed as the parent ID.

X

Finally, we save and activate the flow, thereby completing the configuration.

3.4.4. Result

We enter a website in the "Website" field at the lead level and reload the page. We see that all fields have been filled in correctly.

X

Detailed process:

1. Enter website: A user enters a website into the website field of a lead in Salesforce and saves the record.

2. Flow is triggered: The configured flow is triggered when the lead is saved.

3. Callout to Abstract API: The flow executes a callout to Abstract API via integraid.

4. Data is retrieved: Abstract API returns data for the entered website.

5. Fields are populated: The returned data is written to the corresponding fields of the lead object in Salesforce.

6. Lead is reloaded: When the lead is reloaded, the fields are populated with the data retrieved from Abstract API.

These steps allow you to integrate the information from Abstract API directly into Salesforce and enrich the lead record.