Overview

This guide will show you how to:

  • Create a sync with an API provider
  • Read data from Sequin’s event stream
  • Write data back to the API

Then, you’ll see how to do all this programmatically using Sequin’s Management API.

Create a sync

To get started, you’ll need a Sequin account. If you don’t have one, you can sign up for free. Once you’re logged in, you’ll be prompted to setup your first connection:

In Sequin, an instance of a connection to an API is called a sync. Sequin uses a credential (e.g. an access token) to access the API.

Here are some examples of things you can sync:

  • A Salesforce account
  • A HubSpot sandbox
  • A Shopify store
  • A Stripe account

You can connect to your API account or to your customers’ API accounts. This guide will focus first on connecting to an account you own, but later we’ll show you how to programmatically connect to your customers’ accounts.

In the “Add sync” modal, first select the source API you want to sync with, then:

1

Create a credential

In the “Credential” section, click + Add New. Follow the prompts for your API to issue access to Sequin.

2

Select collections to sync

Under “Collections,” select the data you want to sync. A collection is a type of API object, like a Salesforce Contact or a Shopify Order.

3

Start your sync

Click Start syncing.

Introspect

After starting your sync, introspect the shape of objects flowing from the API. Click the “Records” tab to see the list of records Sequin has extracted so far:

You can click on any record to see an expanded view.

Next, click on the “Events stream” tab to see a live feed of events for this sync. Each event represents a change to a record in the API:

You can make changes to records in the API and see the corresponding events appear in real-time!

Read data

Integrations need to read data in two ways: at rest and in motion. Sequin gives you solutions for both:

At rest

Databases are built for working with data at rest. You can stream data to your database using a Sequin consumer.

To setup a consumer, click the “Consumers” tab in the Sequin console. Then, click + Add New. Map API collections tables in your database:

For a full walkthrough of setting up a database consumer, see the setup guide.

After creating your consumer, Sequin backfills your tables with all the records in the API. Then it streams new data to your database as it arrives.

With your API data in Postgres, you can easily run queries like this:

select * from salesforce.contact
inner join salesforce.opportunity
on contact.id = opportunity.contact_id
where opportunity.amount > 10000
and opportunity.stage = 'Closed Won'

SQL is far more expressive than any HTTP API.

Data in motion

For data in motion, a database like Postgres isn’t the best fit. Instead, you can:

  • Use Sequin’s Stream APIs to consume events
  • Stream data to a stream-processing platform like Kafka or NATS
  • Stream data to your app via webhooks

Kafka, NATS, and webhooks are supported consumers on Sequin. Like Postgres, you can add them in the Sequin console or via the Management API.

For Kafka or NATS, after connecting Sequin to your cluster, you’ll tell Sequin where to publish records and events.

For webhooks, you’ll provide Sequin with a URL to send events to. Sequin will send a POST request to your webhook URL for each event.

Alternatively, you can consume events directly from Sequin via the Stream APIs. Sequin’s Stream APIs are powered by NATS, and so have powerful concepts like batching and consumers. You can paginate through all records across syncs or filter down to specific syncs or collections. As an example:

curl https://api.sequin.io/v1/http-consumers/{id}/next?batch_size=10
200 OK
[
  {
    "ack_token": "NjA1",
    "record": {
      "sync_id": "my-sync-id",
      "collection_id" : "stripe:subscription",
      "upstream_id": "sub_tognkns00nj",
      "upstream_created_at": "2024-11-10T18:38:00.070453Z",
      "upstream_updated_at": "2024-11-10T18:38:00.070453Z",
      "data": {
        "id": "sub_tognkns00nj",
        "object": "subscription",
        "billing": "charge_automatically",
        // …
      }
    }
  },
  // ...
]

Mutate data

On top of reading data, your integration probably needs to write data back to APIs as well. Sequin has a mutation API that allows you to create, update, and delete API records.

With the mutation API, mutations look the same regardless of the API. The data payload for API records matches the same shape used everywhere in Sequin.

Mutations are linked to syncs. When you create a mutation, you’ll specify the sync ID of the sync you want to mutate. Sequin will route the mutation to the right place.

Here’s an example of creating a Salesforce Contact:

curl -X POST \
  https://api.sequin.io/v1/mutations/run \
  -H 'content-type: application/json' \
  -d '{
        "kind": "create",
        "sync_id": "my-sync-id",
        "collection_id": "salesforce:contact",
        "data": [
          {
            "FirstName": "Paul",
            "LastName": "Atreides",
            "Email": "paul@arrakis.org"
          }
        ]
      }'

To learn more about mutations, check out our docs on the mutation API.

Management API

Everything you can do in the Sequin console you can do via Sequin’s Management API. This empowers you to write code that starts syncs, manages consumers, or anything else.

You’ll use the Management API if you’re programmatically connecting to your customers’ API accounts. For example, if you’re building a product that syncs data from your customers’ Salesforce accounts to your app, you’ll use the Management API to capture credentials and spin up syncs for each customer.

You can also use the Management API to integrate Sequin into your development and CI/CD workflows.

There’s a lot you can do with the Management API. Here’s a sampling of some common tasks:

List syncs

List all the syncs in your account:

curl --request GET \
  --url https://api.sequin.io/v1/syncs \
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Add a credential

Add a credential to your account:

curl --request POST \
  --url https://api.sequin.io/v1/credentials \
  --header 'Content-Type: application/json' \
           'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "kind": "stripe_oauth2",
    "access_token": "sk_live_7eC39HqLyjWDarjtT1zdp7dc",
    "oauth_app_id": "8ff58ef0-d376-4ae8-b2e2-9f0206aa65b8",
    "metadata": { "custom_property": 42 }
  }'

Create a sync

Create a new sync using the credential you just created:

curl --request POST
  --url https://api.sequin.io/v1/syncs
  --header 'Content-Type: application/json' \
           'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "provider": "stripe",
    "name": "Choam Corp - Stripe Production",
    "collection_ids": ["stripe:customer", "stripe:invoice"],
    "rate_limit": {
      "allowed_requests": 100,
      "interval": 60,
      "max_concurrent_requests": 0
    },
    "credential_id": "8ff58ef0-d376-4ae8-b2e2-9f0206aa65b8",
    "metadata": { "custom_property": 42 }
  }'

Questions and support

If you have any issues or questions, don’t hesitate to reach out. We’d love to hear what you’re building.