Create a destination using the Stitch Connect API.
Prerequisites
Access to Stitch Connect and valid Connect API credentials. Connect access is a Stitch Advanced or Premium feature. Refer to the Connect API reference for more info on obtaining API credentials.
A Stitch account.
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:
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:
{
"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 bepostgres.-
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 -
ssl -
username
-
This request will complete the form step outlined in the destination’s report card, which you retrieved in Step 2:
curl -X "POST" "https://api.stitchdata.com/v4/destinations" \
-H 'Authorization: Bearer [ACCESS_TOKEN]' \
-H 'Content-Type: application/json' \
-d \
'{
"type": "postgres",
"name": "Staging",
"description": "Postgres database for the staging environment.",
"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):
{
"description": "Postgres database for the staging environment.",
"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": "Staging",
"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:
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):
{
"description": "Postgres database for the staging environment.",
"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": "Staging",
"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.