Creating an external source

Instead of copying and updating data from various places, external sources let you get up-to-date information directly from external systems—like ERP, CRM, inventory, pricing, e-commerce platforms, other CMSs, or any REST API—and pull live data in real time when content is generated.

By creating an external source, you establish a connection with an external service by providing key details such as the endpoint URL, HTTP method (GET or POST), authentication method (for example, API key, login/password, OAuth2 Client Credentials, or SHA256-based), and other settings. During content generation—when an object with a record is generated or a record is previewed for the context of a specific profile in the editor—Synerise sends a request to the configured endpoint.

In the configuration of the external source, you can also use Jinjava (for example, in the endpoint URL or request body) to dynamically pass profile information in the request. At the end of the external source configuration, a preview cURL command is provided, which you can copy and test in your terminal or API testing tool.

This integration lets external data appear seamlessly as part of your content, just like data stored directly inside Brickworks. External sources eliminate multi-system integration complexity while ensuring your content remains accurate, complete, and contextually relevant—making it a live reflection of your entire business ecosystem.

Benefits

• Content always reflects the latest state of your business systems. Inventory counts, pricing, customer data, and metrics are fetched live when content is requested.
• Your applications make one API call to Brickworks and receive complete, enriched content that combines your managed content with live external data.
• No ETL jobs to monitor, no data synchronization to manage, no stale data concerns. External systems remain the single source of truth.
• External sources can use context parameters and other record's simple fields to fetch precisely the right data for each request, enabling dynamic, personalized content experiences.

Example use cases

You can use external sources in the following cases:

• E-commerce operations - You can combine static product information from a record with live data such as current inventory levels, pricing updates, customer ratings, and shipping costs pulled directly from your backend or e-commerce platform. You also add personalized product suggestions based on what each customer has recently viewed. This way, the product details you show are always accurate and tailored for each shopper in real time.
• Customer experience platforms - You can merge personalized data created inside Synerise — like recent product views or preferences—with up-to-date information about the customer’s account or status pulled from your external CRM or other backend systems. For example, you could show each customer their current membership level or available offers alongside personalized clothing recommendations, all combined into one seamless experience.
• Legacy CMS modernization - If you’re still using an older CMS for your website content, you can fetch static content (like text and images) from your legacy CMS, then enrich it by adding AI-driven Synerise product recommendations, personalized promotions, and personalized messages without needing to move your content elsewhere.

Procedure

1. Go to Data Modeling Hub > External sources > New external source.
   Result:
   

   

2. Select the method of authorization to the external source to which you will make a request.

   Custom connectionLogin & PasswordSynerise API keyOAuth2 Client CredentialsSHA256-based authenticationAPI KeyWithout authentication

   This method sends an authentication token request before executing the main request defined in the external source settings. The token is fetched when the request data is uncached, then cached according to its TTL, and added to the target request.

   1. Click Select connection.
   2. In the connection list:
      • If the connection you want to use is in the list, select it and proceed to selecting the HTTP method.
      • If the connection list is empty or you don't see a connection, you must:

        1. At the top of the dropdown list, click Add connection.

        2. In the Authorization request tab, click Define.
        3. In the Connection name field, enter the name of your connection (it's visible only on the Select connection dropdown list or on the list of connections in Settings > Connections).
        4. In Secret, enter a value which is required in the request to obtain a token. This value will be anonymized and displayed as asterisks.
        5. In URL, from the dropdown list, select the method and provide the URL to which the request will be sent.
        6. In the Headers section, add request headers (in the left field, enter the key; in the right, enter its value).
        7. In the Body field, enter the request body.
           For example:
           

           {
                           "api-key": "{{secret}}"
                           }

           where {{secret}} retrieves the value of the Secret field to anonymize the token.
        8. Confirm the settings in the Authorization request tab by clicking Apply.
        9. In the Token placement settings section, click Define.
        10. Click Authorization response.

        11. If you:

            • specify the value in the Headers section, the extracted authorization data from the response will be added as a header to the target request.

            • provide the value in the URL Parameters section, the data will be appended to the target request’s URL as a parameter.
              You can use the following values to retrieve values from the response:

              • authResponseBody - a variable that contains the full body of an authentication response
              • authResponseStatusCode - a variable that contains the status code of an authentication response
              • authResponseHeaders- a variable that contains the headers of an authentication response
                For example:

              Bearer {{ authResponseBody | fromjson | attr("token") }}

            It takes the JSON response body stored in authResponseBody, parses it into a usable structure, and extracts the value of the token field. Outputs a string like: Bearer "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

        12. In TTL field, specify how long the cached response from the external request will be valid.
            If you leave this field empty, it's 60 seconds.
        13. Confirm by clicking Create.
            You can reuse this connection in other external sources and in Workflows.

   This method lets you use basic authentication to authenticate with the remote server.

   1. Click Select connection.
   2. In the connection list:
      • If the connection you want to use is in the list, select it and proceed to selecting the HTTP method.
      • If the connection list is empty or you don't see a connection, you must:
        1. At the top of the dropdown list, click Add connection.
        2. In the Connection name field, enter the name of your connection (it's visible only in Synerise).
        3. In the Login field, enter a login.
        4. In the Password field, enter the password.
        5. Click Create.
           You can reuse this connection in other external sources and in Workflows.

   This method is particularly recommended for the users who use Synerise REST API. It lets you select a connection that includes an API key with the required permissions. This way, the requests to Synerise API are executed by this integration and a JWT is not required as it is generated while sending requests and attached to the request headers.

   1. Click Select connection.
   2. If the connection you want to use is in the list, select it and fill in the configuration.
      • If the connection list is empty or you don't see a connection, you must:
        1. At the top of the dropdown list, click Add connection.
        2. In the Connection name field, enter the name of your connection (it's visible only in Synerise).
        3. From the API key dropdown, select the API key.
           If the list is empty, make sure your user role includes the permission to preview API keys.
        4. Click Create.
           You can reuse this connection in other external sources and in Workflows.

   This method lets you use your OAuth2 credentials to authorize.

   1. Click Select connection.
   2. In the connection list:
      • If the connection you want to use is in the list, select it and proceed to selecting the HTTP method.
      • If the connection list is empty or you don't see a connection, you must:
        1. At the top of the dropdown list, click Add connection.
        2. In the Connection name field, enter the name of your connection (it's visible only in Synerise).
        3. In the Token endpoint URL field, enter the URL used to obtain an access token from the authorization server.
        4. In the Client ID field, enter a unique identifier assigned to your application by the service provider.
        5. In the Client secret field, enter a confidential key issued alongside the Client ID. It is used to securely authenticate your application.
        6. Optionally, in the Scope field, define the level of access your application is requesting. Scopes specify which actions or data your application can access (for example, read user data, send messages). Refer to the API documentation for the correct scope values.
        7. Click Create.
           You can reuse this connection in other external sources and in Workflows.

   This method is recommended exclusively for connecting with Eagle Eye. This method lets you authenticate using the SHA256 algorithm. When a target request is sent, the following headers are added to the request:

   • X-EES-AUTH-CLIENT-ID - the value is taken from the Client ID field.
   • X-EES-AUTH-HASH - the value is generated by concatenating the endpoint URI, request body, and client secret, and then hashing the result using SHA256.

   1. Click Select connection.
   2. In the connection list:
      • If the connection you want to use is in the list, select it and proceed to selecting the HTTP method.
      • If the connection list is empty or you don't see a connection, you must:
        1. At the top of the dropdown list, click Add connection.
        2. In the Connection name field, enter the name of the connection.
           It's used to find the connection on the list.
        3. In Client ID, enter a unique identifier assigned to your application by the service provider.
        4. In Client secret, enter the client secret assigned to your application by the service provider.
        5. Confirm by clicking Create.
           You can reuse this connection in other external sources and in Workflows.

   This method lets you authenticate using an API secret by including it in a header of your choice or in a URL parameter. Example outputs:

   • the authorization header: Authorization: Bearer [secret]
   • URL parameter: client_id=[rendered secret]

   When you use this connection, the token will be automatically added to either the request header or the request URL with every request.

   1. Click Select connection.
   2. If the connection you want to use is in the list, select it and proceed to selecting the HTTP method.
      • If the connection list is empty or you don't see a connection, you must:
        1. At the top of the dropdown list, click Add connection.
        2. In the Connection name field, enter the name of your connection (it's visible only in Synerise).
        3. In the Secret field, enter an API Key.
        4. If you:
           • specify the value in the Headers section, the API key will be added as a header to the request. For example, x-api-key: {{secret}} where {{secret}} retrieves the value of the Secret field to anonymize the API key value.
           • provide the value in the URL Parameters section, the API key will be appended to the request’s URL as a parameter.
        5. Click Create.
           You can reuse this connection in other external sources and in Workflows.

   No authentication is required.

3. From the Method dropdown list, select the request method to specify how the request will be sent.
4. In URL, provide the endpoint address to which the request will be made. You can include query parameters directly in the URL, for example: https://example.com/products?productId={{profile.id}}&lang={{profile.language}}. Values of query parameters can use Jinjava, which allows you to dynamically pass profile data or record field values in the request. If the same parameter is defined both in the URL query string and in the Additional parameters section, the value from Additional parameters overrides the value from the URL. Because of this, parameters defined in the URL do not need to be repeated in Additional parameters unless you want to overwrite them.
5. In TTL, specify how long the cached response from the external request will be valid. After changing data, the old value can be visible through brickworks for a maximum time defined here. You can set maximum 1800s value.
   We recommend setting short TTL for fast-changing data and longer for stable information.
6. In the Headers section, by clicking Add header, you can define the request headers such as content-type: application/json in the key-value form: in the left field (key) provide a header name, in the right field, provide a value.
   These headers will be used in all schemas where you use this data source.

7. If you selected the POST method, you must provide the request body in the Body section.

   IMPORTANT: The content of the request body may be returned during object generation when the Return error details when the source responds with an error option is enabled in a schema. In such cases, you can remove sensitive data carried over from the request body by using Response transformers.

   • Optionally, by clicking , you can use a snippet which will let you add dynamic values to the request body.
   • If you used snippets, enable processing of the Jinjava template by selecting the fields in a request that contain them in the Treat the body selected parameters as Jinjava section.
   • You can use the following options:
     • From the Cast to dropdown list, select the data type to cast the Jinjava result to
     • Use the Strict toggle to define what happens when casting is not successful:
       • when the option is disabled, sets Jinjava to a null value,
       • when the option is enabled, returns an error in generating an object from a record
         The indicated parameter will be rendered as Jinjava by the backend and you can define the value type returned.

     

8. In the Additional parameters section, by clicking Add parameter, you can add custom parameters to the events generated by the response from the external source. In the left field (key) provide a parameter name; in the right field, provide its value.

   • You can use this, for example, to create a common parameter for events from a particular external source.
   • The parameters will be added to brickwork.generated and/or brickwork.generated.error events.

Testing the external source

In the Preview cURL section, you can view the cURL request that will be sent to the endpoint when invoking the object with the record result or previewing a record that references an external source.

You can copy this cURL command and run it in your terminal or use it with any API testing tool to see how the request works.

Using external sources in a record

See the External Data section.