Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Heroku Enterprise
  • Heroku Connect (Salesforce sync)
  • Quick Start: Heroku Connect API

Quick Start: Heroku Connect API

English — 日本語に切り替える

Last updated February 06, 2023

Table of Contents

  • Prerequisites
  • Step 1: Create a Heroku App and Heroku Postgres Database
  • Step 2: Provision the Heroku Connect Add-on
  • Step 3: Add a User to Heroku Connect
  • Step 4: Note Your Connection Info for Subsequent API Calls
  • Step 5: Configure the Database and Schema
  • Step 6: Authenticate the Connection to Your Salesforce Org
  • Step 7: Export a Mapping Configuration
  • Step 8: Import a Mapping Configuration
  • Step 9: Create a Mapping
  • Step 10: Monitor the Connection and Mapping Status
  • Next Steps

We recommend using our low-cost plans to complete this tutorial. Eligible students can apply for platform credits through our new Heroku for GitHub Students program.

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.

Adding a database to complete this tutorial counts towards your usage. Delete your database as soon as you’re done to control costs. Learn about our low-cost plans. Eligible students can apply for platform credits through our Heroku for GitHub Students program.

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 mini 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 mini 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

See OAuth for instructions on getting your direct authorization (bearer) token.

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.

There’s no programmatic way to complete this step. Salesforce authentication requires manually visiting the URL and authenticating with both Heroku and Salesforce.

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.

Keep reading

  • Heroku Connect (Salesforce sync)

Feedback

Log in to submit feedback.

Writing Data to Salesforce with Heroku Connect Quick Start: Heroku Connect CLI

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences