Create a destination using the Stitch Connect API.

Note: Stitch currently supports one destination per account.


Prerequisites

  • Access to Stitch Connect and valid Connect API credentials. Connect access is a Stitch Enterprise feature. Refer to the Connect API reference for more info on obtaining API credentials.

  • A Stitch account that doesn’t currently have a destination. Stitch currently supports one destination per account. If you already have a destination connected to your account, you’ll need to delete it before continuing. Note: Replication will be paused until a new destination is created and configured.


Step 1: Get the destination's API type

To get started, you’ll need to identify the API type of the destination you want to create. Every destination available in the Connect API has a type which is unique to that destination.

For example: The API type for an PostgreSQL destination is postgres.

Refer to the Connection Property Reference to locate the API type for your destination.


Step 2: Get the destination's report card

When preparing for destination creation, the next step is to get the report card for the destination you want to create. The report card contains information about the steps required to fully configure the connection.

Use the GET /v4/destination-types/{destination_type} endpoint to get the report card for the destination. In this example, we’re retrieving the report card for a postgres destination:

GET /v4/destination-types/{destination_type}
curl "https://api.stitchdata.com/v4/destination-types/postgres" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be a destination object with a Connection step object:

Response for GET /v4/destination-types/{destination_type}
{
  "type": "postgres",
  "current_step": 1,
  "current_step_type": "form",
  "steps": [
    {
      "type": "form",
      "properties": [
        {
          "name": "database",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        },
        {
          "name": "encryption_host",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        },
        {
          "name": "encryption_port",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "pattern": "^\\d+$"
          },
          "provided": false
        },
        {
          "name": "encryption_type",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "pattern": "^(ssh|none)$"
          },
          "provided": false
        },
        {
          "name": "encryption_username",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        },
        {
          "name": "host",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        },
        {
          "name": "password",
          "is_required": true,
          "is_credential": true,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        },
        {
          "name": "port",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "pattern": "^\\d+$"
          },
          "provided": false
        },
        {
          "name": "ssl",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string",
            "pattern": "^(true|false)$"
          },
          "provided": false
        },
        {
          "name": "sslrootcert",
          "is_required": false,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        },
        {
          "name": "username",
          "is_required": true,
          "is_credential": false,
          "system_provided": false,
          "property_type": "user_provided",
          "json_schema": {
            "type": "string"
          },
          "provided": false
        }
      ]
    },
    {
      "type": "fully_configured",
      "properties": []
    }
  ],
  "details": {
    "pricing_tier": "standard",
    "pipeline_state": "released",
    "protocol": "postgres",
    "access": true
  }
}

Note: To create the destination in your account, the details.access property must be true. This indicates that the plan your Stitch account is using has access to the destination.

For PostgreSQL destinations, only the form step must be completed to fully configure the destination. To complete the step, you’ll need to provide values for all required user-provided properties. These properties will have a is_required: true value and a property_type: user_provided value. Refer to the PostgreSQL Destination Form Property documentation for more info about these properties.


Step 3: Create the destination and complete the form step

Use the POST /v4/destinations endpoint to create the PostgreSQL destination. The request body must include the following properties:

  • type: The API type of the destination. In this example, this value will be postgres.
  • properties: A Properties object containing the properties required to configure the destination. Refer to the destination connection property documentation for your destination for more info about the required properties.

    For postgres, the required properties are:

    • database

    • encryption_type

    • host

    • password

    • port

    • username

This request will complete the form step outlined in the destination’s report card, which you retrieved in Step 2:

POST /v4/destinations
curl -X "POST" "https://api.stitchdata.com/v4/destinations" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json' \
     -d \
'{
  "type": "postgres",
  "properties": {
    "database": "[DATABASE]",
    "encryption_type": "none",
    "host": "[HOST_ADDRESS]",
    "password": "[PASSWORD]",
    "port": "5432",
    "ssl": "false",
    "username": "[USERNAME]"
  }
}'

The response will be a destination object containing the destination’s ID, report card, and current configuration status (report_card.current_step_type):

Response for POST /v4/destinations
{
  "properties": {
    "database": "[DATABASE]",
    "encryption_type": "none",
    "host": "[HOST_ADDRESS]",
    "port": "5432",
    "ssl": "false",
    "username": "[USERNAME]"
  },
  "updated_at": "2021-06-03T16:11:03Z",
  "check_job_name": "116078.337658.check.8934a4cd-4d60-48c9-85e4-e95cab6d4cae",
  "name": "Default Warehouse",
  "type": "postgres",
  "deleted_at": null,
  "system_paused_at": null,
  "stitch_client_id": 116078,
  "paused_at": null,
  "id": 337658,
  "display_name": null,
  "created_at": "2021-06-03T16:11:03Z",
  "report_card": {
    "type": "postgres",
    "current_step": 2,
    "current_step_type": "fully_configured",
    "steps": [
      {
        "type": "form",
        "properties": [
          {
            "name": "database",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          },
          {
            "name": "encryption_host",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": false
          },
          {
            "name": "encryption_port",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^\\d+$"
            },
            "provided": false
          },
          {
            "name": "encryption_type",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^(ssh|none)$"
            },
            "provided": true
          },
          {
            "name": "encryption_username",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": false
          },
          {
            "name": "host",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          },
          {
            "name": "password",
            "is_required": true,
            "is_credential": true,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          },
          {
            "name": "port",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^\\d+$"
            },
            "provided": true
          },
          {
            "name": "ssl",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^(true|false)$"
            },
            "provided": true
          },
          {
            "name": "sslrootcert",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": false
          },
          {
            "name": "username",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          }
        ]
      },
      {
        "type": "fully_configured",
        "properties": []
      }
    ]
  }
}

Step 4: Check the destination's configuration status

After the destination is created, Stitch will automatically perform a connection check using the details provided in the properties object. If the check is successful, Sttich will advance to the next step in the destination’s configuration.

In this example, the only step required for our PostgreSQL is the form step. The destination’s configuration status should be fully_configured if the connection check was successful, meaning Stitch can begin loading replicated data into the destination.

You can verify the destination’s configuration status by sending a request to GET /v4/destinations:

GET /v4/destinations
curl "https://api.stitchdata.com/v4/destinations" \
     -H 'Authorization: Bearer [ACCESS_TOKEN]' \
     -H 'Content-Type: application/json'

The response will be a destination object containing the destination’s current configuration status (report_card.current_step_type):

Response for GET /v4/destinations
{
  "properties": {
    "database": "[DATABASE]",
    "encryption_type": "none",
    "host": "[HOST_ADDRESS]",
    "port": "5432",
    "ssl": "false",
    "username": "[USERNAME]"
  },
  "updated_at": "2021-06-03T16:11:03Z",
  "check_job_name": "116078.337658.check.8934a4cd-4d60-48c9-85e4-e95cab6d4cae",
  "name": "Default Warehouse",
  "type": "postgres",
  "deleted_at": null,
  "system_paused_at": null,
  "stitch_client_id": 116078,
  "paused_at": null,
  "id": 337658,
  "display_name": null,
  "created_at": "2021-06-03T16:11:03Z",
  "report_card": {
    "type": "postgres",
    "current_step": 2,
    "current_step_type": "fully_configured",
    "steps": [
      {
        "type": "form",
        "properties": [
          {
            "name": "database",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          },
          {
            "name": "encryption_host",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": false
          },
          {
            "name": "encryption_port",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^\\d+$"
            },
            "provided": false
          },
          {
            "name": "encryption_type",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^(ssh|none)$"
            },
            "provided": true
          },
          {
            "name": "encryption_username",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": false
          },
          {
            "name": "host",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          },
          {
            "name": "password",
            "is_required": true,
            "is_credential": true,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          },
          {
            "name": "port",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^\\d+$"
            },
            "provided": true
          },
          {
            "name": "ssl",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string",
              "pattern": "^(true|false)$"
            },
            "provided": true
          },
          {
            "name": "sslrootcert",
            "is_required": false,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": false
          },
          {
            "name": "username",
            "is_required": true,
            "is_credential": false,
            "system_provided": false,
            "property_type": "user_provided",
            "json_schema": {
              "type": "string"
            },
            "provided": true
          }
        ]
      },
      {
        "type": "fully_configured",
        "properties": []
      }
    ]
  }
}

Next steps

Congratulations on configuring a destination using the Connect API! Now that you’ve got a destination, start creating data sources and get your data flowing.

Check out the Tutorials and resources to see what else you can do with Stitch Connect.