Last updated May 08, 2024

Heroku Connect provides an API to automate the creation, maintenance, and monitoring of sync operations between Salesforce and a Heroku PostgreSQL database. This guide helps you get started with using Heroku Connect via its API.

Prerequisites

This guide assumes that you have:

• A verified Heroku Account
• The Heroku CLI plugin installed.
• A Heroku Platform API direct authorization token. You use this token to authenticate your Heroku Connect API calls. This bearer token is for your own application’s Heroku user only. Heroku Connect doesn’t support API access on behalf of other Heroku customers.

Step 1: Create a Heroku App and Heroku Postgres Database

Heroku Connect requires Heroku Postgres for syncing data from Salesforce. Both Heroku Connect and Heroku Postgres are add-ons and must be attached to a Heroku app. You can attach add-ons to an empty app - deploying code isn’t required.

Create an empty app and attach Heroku Postgres to it:

1. Create an app with the following Heroku CLI command: heroku apps:create
2. Provision the database with the following Heroku CLI command: heroku addons:create heroku-postgresql:PLAN_NAME. If no plan name is specified, the essential-0 plan is provisioned but this default isn’t recommended. Choose a -4 plan or larger for production use cases. See Heroku Connect for more info. For tutorial purposes only, you can choose the essential-0 plan to minimize costs.

Step 2: Provision the Heroku Connect Add-on

Run the following Heroku CLI command: heroku addons:create herokuconnect:PLAN_NAME.

If no plan name is specified, the demo plan is provisioned. See Available Plans for more info.

Step 3: Add a User to Heroku Connect

By default, no users are present on a Heroku Connect add-on. Add your Heroku user account to the access list with this endpoint:

POST https://hc-central.heroku.com/auth/<app_name_or_app_uuid>

Example:

$ curl -X POST https://hc-central.heroku.com/auth/example-app \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

This returns all Connect add-ons across all regions that you have access to, including your newest connection. You can filter the response with a tool like jq.

Example response:

{"user": {"id": "86fa36aa-a8de-4b97-8c5b-6dcfb44180ad", "email": "example-user@example.com"}, "connections": [{"id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4", "resource_name": "herokuconnect-defined-93233"...}

Step 4: Note Your Connection Info for Subsequent API Calls

The response you received from completing the previous step includes a region_url. Adding /api/v3 to the end of this region_url gives you the root Heroku Connect API v3 URL for your connection. Use this root URL for the rest of your Heroku Connect API requests. See Root Endpoints for more info. If you have multiple connections, ensure you’re noting down info for the new one you created.

The examples in this guide assume the app is in the Virginia region, with a root API URL of https://connect-3-virginia.heroku.com/api/v3.

The response also includes the connection’s id for your newly created connection. Note this id down for use in subsequent API calls.

Step 5: Configure the Database and Schema

Configure the connection with the config var name of your database and an unused schema name to store Salesforce data. Typically, these values are DATABASE_URL and salesforce.

Send a PATCH call to configure these values. The db_key corresponds to your database config var. Use the connection’s id value you noted in the previous step in your endpoint.

PATCH /connections/<connection_id>

Example:

$ curl -X PATCH https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4 \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json" \
-d '{"schema_name": "salesforce", "db_key": "DATABASE_URL"}'

Example response:

{
  "id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
  "name": "example-app",
  "resource_name": "herokuconnect-defined-93233",
  "schema_name": "salesforce",
  "db_key": "DATABASE_URL",
  ...
}

Step 6: Authenticate the Connection to Your Salesforce Org

Authenticate Heroku Connect to talk to your Salesforce org by retrieving the authorization URL. The Salesforce user opens this URL to complete the authentication. In a typical application, you can retrieve the authorization URL and link it to a button to show to the user.

POST /connections/<connection_id>/authorize_url

Example:

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/authorize_url \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json" \
-d '{"environment": "production"}'

Example response: term {"redirect": "https://connect-3-virginia.heroku.com/oauth/start/…"}

Visit the URL in that redirect field to complete the authentication.

You can see all available JSON parameters here.

Step 7: Export a Mapping Configuration

You create mappings to configure the objects and fields that sync from Salesforce. The easiest way to do so is to import an existing configuration.

If you have an existing Heroku Connect connection with mappings configured, you can export out its configuration as JSON to import into a new connection. Skip to step 9 if you don’t have another existing connection.

You can export a configuration file from the Heroku Connect dashboard or via the API:

POST /connections/<connection_id>/actions/export

Example:

curl -X GET https://connect-3-virginia.heroku.com/api/v3/connections/1ac07199-0ddb-43e9-9865-8d9721ca6c6e/actions/export \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
--output config.json

This example uses --output to save the JSON response to a config.json file. The connection ID used is different from the ones used in other steps since it’s exporting the configuration of another connection.

Example response when --output isn’t used:

{"mappings":[{"object_name":"Account","config":{"access":"read_write","sf_notify_enabled":false,"sf_polling_seconds":600,...}

Step 8: Import a Mapping Configuration

Import your configuration file with this endpoint:

POST /connections/<connection_id>/actions/import

This endpoint accepts the configuration details either as a standard file upload or directly as JSON in the request body.

Example:

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/actions/import \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-F "config=@config.json"

Or:

$ curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/actions/import \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H "Content-Type: application/json"  \
-d @config.json

If there’s no error indicated in the response, go to step 10 to check the status of your connection and mappings.

Step 9: Create a Mapping

You can skip this step if you exported and imported a configuration file in steps 7 and 8 unless you want to create additional mappings.

In addition to being able to import an entire configuration at once, you can add a single mapping at a time to an existing connection using this endpoint:

POST /connections/<connection_id>/mappings

The JSON payload for this API endpoint contains the detailed configuration for the mapping itself.

The payload in the following example configures a read-write mapping that syncs specific fields of the Account object.

Example:

curl -X POST https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4/mappings \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8" \
-H 'Content-Type: application/json' \
-d @- << EOF
{
  "object_name": "Account",
  "config": {
    "access": "read_write",
    "sf_notify_enabled": true,
    "sf_polling_seconds": 600,
    "fields": {
      "CreatedDate": {},
      "Id": {},
      "IsDeleted": {},
      "Name": {},
      "SystemModstamp": {}
    },
    "indexes": {
      "Id": {
        "unique": false
      },
      "SystemModstamp": {
        "unique": false
      }
    }
  }
}
EOF

For more info on the expected payload for this API request, see Create a Mapping.

Example response:

{"id":"19f75004-8383-426e-9f33-5a811f5c8f78","_id":213914,"object_name":"Account","state":"SCHEMA_CHANGED","config":{"access":"read_write"...}

You can repeat this step for as many Salesforce objects as you’d like to sync.

Step 10: Monitor the Connection and Mapping Status

Use the connection detail API endpoint.

GET /connections/<connection_id>

The deep query string parameter allows you to return information about the connection’s mappings, in addition to the connection itself.

Example:

$ curl -X GET "https://connect-3-virginia.heroku.com/api/v3/connections/c08fdb87-a196-46aa-8b44-5ad6e9e253c4?deep=true" \
-H "Authorization: Bearer 86b831b4-c3e8-4a3f-93bf-ca9ffa6dfdc8"

The response contains details about your connection and mappings. Check that the state of your connection and mappings to ensure things are working as expected. See the Connection States Reference and the Mapping States Reference articles for more info.

Example response:

{
  "id": "c08fdb87-a196-46aa-8b44-5ad6e9e253c4",
  "name": "example-app",
  "resource_name": "herokuconnect-defined-93233",
  "schema_name": "salesforce",
  "db_key": "DATABASE_URL",
  "state": "IDLE",
  "mappings": [
    {
      "id": "7b5a2105-9845-43cd-9648-9406ee745bf5",
      "object_name": "Account",
      "state": "DATA_SYNCED",
      …
    },
    {
      "id": "3f87cb43-2b2b-4a40-a396-d3611cb776b4",
      "object_name": "Contact",
      "state": "DATA_SYNCED",
      …
    },
    …
  ]
  …
}

Next Steps

In this tutorial, you set up an empty Heroku app. To deploy code to this app, see these articles on deployments. Most users deploy their code with Git.

To connect to your Heroku Postgres database from your Heroku app, see Heroku Postgres.

To connect to Heroku Postgres from external connections, see External Connections (ingress) and Heroku Postgres on Private and Shield Spaces.

See Heroku Connect API for other API operations you can perform.