Sign in

v1

latestOpenAPI 3.0.3Apache 2.02026-07-133681213.9 KB
Connections

Create connection

Create an authorized connection

post/vault/connections/{unified_api}/{service_id}

Path parameters

service_idstring required

Service ID of the resource to return

unified_apistring required

Unified API

Headers

x-apideck-consumer-idstring required

ID of the consumer which you want to get or push data from

x-apideck-app-idstring required

The ID of your Unify application

Request body

idstring

The unique identifier of the connection.

service_idstring

The ID of the service this connection belongs to.

namestring

The name of the connection

tag_linestring
unified_apistring

The unified API category where the connection belongs to.

state'available' | 'callable' | 'added' | 'authorized' | 'invalid'

Connection state flow

integration_state'disabled' | 'needs_configuration' | 'configured'

The current state of the Integration.

auth_type'oauth2' | 'apiKey' | 'basic' | 'custom' | 'none'

Type of authorization used by the connector

oauth_grant_type'authorization_code' | 'client_credentials' | 'password'

OAuth grant type used by the connector. More info: https://oauth.net/2/grant-types

status'live' | 'upcoming' | 'requested'

Status of the connection.

enabledboolean

Whether the connection is enabled or not. You can enable or disable a connection using the Update Connection API.

websitestring

The website URL of the connection

iconstring

A visual icon of the connection, that will be shown in the Vault

logostring

The logo of the connection, that will be shown in the Vault

authorize_urlstring nullable

The OAuth redirect URI. Redirect your users to this URI to let them authorize your app in the connector's UI. Before you can use this URI, you must add redirect_uri as a query parameter to the authorize_url. Be sure to URL encode the redirect_uri part. Your users will be redirected to this redirect_uri after they granted access to your app in the connector's UI.

revoke_urlstring nullable

The OAuth revoke URI. Redirect your users to this URI to revoke this connection. Before you can use this URI, you must add redirect_uri as a query parameter. Your users will be redirected to this redirect_uri after they granted access to your app in the connector's UI.

settingsobject nullable

Connection settings. Values will persist to form_fields with corresponding id

configurable_resourcesstring[]
resource_schema_supportstring[]
resource_settings_supportstring[]
validation_supportboolean
schema_supportboolean
settings_required_for_authorizationstring[]

List of settings that are required to be configured on integration before authorization can occur

has_guideboolean

Whether the connector has a guide available in the developer docs or not (https://docs.apideck.com/connectors/{service_id}/docs/consumer+connection).

consent_state'implicit' | 'pending' | 'granted' | 'denied' | 'revoked' | 'requires_reconsent'

The current consent state of the connection

health'revoked' | 'missing_settings' | 'needs_consent' | 'pending_confirmation' | 'needs_auth' | 'pending_refresh' | 'ok' | 'degraded'

Operational health status of the connection

credentials_expire_atnumber

Unix timestamp in milliseconds when credentials will be deleted if token refresh continues to fail. A value of 0 indicates no active retention window (connection is healthy or not using OAuth token refresh).

last_refresh_failed_atnumber

Unix timestamp in milliseconds of the last failed token refresh attempt. A value of 0 indicates no recent failures. This field is used internally to enforce cooldown periods between retry attempts.

last_downstream_error_atnumber

Unix timestamp in milliseconds of the last downstream unreachable error (502/504 network class). A value of 0 indicates no active error. Connection remains callable while this is set; health surfaces as 'degraded'.

created_atnumber
updated_atnumber nullable

Example request

{
  "id": "crm+salesforce",
  "service_id": "salesforce",
  "name": "Salesforce",
  "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
  "unified_api": "crm",
  "state": "authorized",
  "integration_state": "configured",
  "auth_type": "oauth2",
  "oauth_grant_type": "authorization_code",
  "enabled": true,
  "website": "https://www.salesforce.com",
  "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
  "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
  "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
  "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
  "settings": {
    "instance_url": "https://eu28.salesforce.com",
    "api_key": "12345xxxxxx"
  },
  "metadata": {
    "account": {
      "name": "My Company",
      "id": "c01458a5-7276-41ce-bc19-639906b0450a"
    },
    "plan": "enterprise"
  },
  "form_fields": [
    {
      "id": "instance_url",
      "label": "Instance url",
      "value": "https://eu28.salesforce.com",
      "placeholder": "",
      "mask": false,
      "type": "text",
      "required": true,
      "disabled": false,
      "custom_field": false,
      "sensitive": false
    },
    {
      "id": "api_key",
      "label": "API Key",
      "value": "123455677",
      "placeholder": "",
      "mask": false,
      "type": "text",
      "required": true,
      "disabled": false,
      "custom_field": false,
      "sensitive": true
    }
  ],
  "configuration": [
    {
      "resource": "leads",
      "defaults": [
        {
          "target": "custom_fields",
          "id": "ProductInterest",
          "options": [
            {
              "label": "General Channel",
              "value": "general"
            }
          ],
          "value": "GC5000 series"
        }
      ]
    }
  ],
  "configurable_resources": [
    "opportunities",
    "companies",
    "contacts",
    "leads"
  ],
  "resource_schema_support": [
    "leads"
  ],
  "resource_settings_support": [
    "leads"
  ],
  "settings_required_for_authorization": [
    "client_id",
    "client_secret"
  ],
  "subscriptions": [
    {
      "downstream_id": "5f5f5f5f5f5f5f5f5f5f5f5f",
      "unify_event_types": [
        "crm.contact.created"
      ],
      "downstream_event_types": [
        "contacts.CREATED"
      ],
      "execute_url": "https://unify.apideck.com/webhook/w/{lookupIdToken}/{serviceId}?e={downstreamEventType}",
      "created_at": "2020-10-01T12:00:00.000Z"
    }
  ],
  "has_guide": true,
  "custom_mappings": [
    {
      "id": "hris+employees+first_aid_training",
      "label": "First Aid Training",
      "description": "First Aid Training completed after 2019-01-01",
      "value": "$.root.training.first_aid",
      "key": "first_aid_training",
      "custom_field": true,
      "consumer_id": "test_user_id",
      "example": "Some value"
    }
  ],
  "consent_state": "granted",
  "consents": [
    {
      "id": "con_1234567890",
      "created_at": "2025-04-15T14:30:00Z",
      "granted": true,
      "resources": {
        "hris.employees": {
          "id": {
            "read": true,
            "write": false
          },
          "first_name": {
            "read": true,
            "write": true
          },
          "last_name": {
            "read": true,
            "write": true
          },
          "email": {
            "read": true,
            "write": true
          },
          "addresses[].street": {
            "read": true,
            "write": false
          },
          "addresses[].city": {
            "read": true,
            "write": false
          },
          "employment.job_title": {
            "read": true,
            "write": true
          },
          "custom_fields[].employee_number": {
            "read": true,
            "write": false
          }
        },
        "hris.departments": {
          "id": {
            "read": true,
            "write": false
          },
          "name": {
            "read": true,
            "write": true
          },
          "code": {
            "read": true,
            "write": false
          }
        }
      }
    }
  ],
  "latest_consent": {
    "id": "con_1234567890",
    "created_at": "2025-04-15T14:30:00Z",
    "granted": true,
    "resources": {
      "hris.employees": {
        "id": {
          "read": true,
          "write": false
        },
        "first_name": {
          "read": true,
          "write": true
        },
        "last_name": {
          "read": true,
          "write": true
        },
        "email": {
          "read": true,
          "write": true
        },
        "addresses[].street": {
          "read": true,
          "write": false
        },
        "addresses[].city": {
          "read": true,
          "write": false
        },
        "employment.job_title": {
          "read": true,
          "write": true
        },
        "custom_fields[].employee_number": {
          "read": true,
          "write": false
        }
      },
      "hris.departments": {
        "id": {
          "read": true,
          "write": false
        },
        "name": {
          "read": true,
          "write": true
        },
        "code": {
          "read": true,
          "write": false
        }
      }
    }
  },
  "application_data_scopes": {
    "enabled": true,
    "updated_at": "2025-04-15T14:30:00Z",
    "resources": {
      "hris.employees": {
        "id": {
          "read": true,
          "write": false
        },
        "first_name": {
          "read": true,
          "write": true
        },
        "last_name": {
          "read": true,
          "write": true
        },
        "email": {
          "read": true,
          "write": true
        },
        "addresses[].street": {
          "read": true,
          "write": false
        },
        "addresses[].city": {
          "read": true,
          "write": false
        },
        "employment.job_title": {
          "read": true,
          "write": true
        },
        "custom_fields[].employee_number": {
          "read": true,
          "write": false
        }
      },
      "hris.departments": {
        "id": {
          "read": true,
          "write": false
        },
        "name": {
          "read": true,
          "write": true
        },
        "code": {
          "read": true,
          "write": false
        }
      }
    }
  },
  "health": "ok",
  "credentials_expire_at": 1730172800000,
  "last_refresh_failed_at": 1730000000000,
  "last_downstream_error_at": 1730000000000,
  "created_at": 1615563533390,
  "updated_at": 1616662325753
}

Response

Connection created

status_codeinteger required

HTTP Response Status Code

statusstring required

HTTP Response Status

_rawRaw nullable

Raw response from the integration when raw=true query param is provided

Example response

{
  "status_code": 201,
  "status": "OK",
  "data": {
    "id": "crm+salesforce",
    "service_id": "salesforce",
    "name": "Salesforce",
    "tag_line": "CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.",
    "unified_api": "crm",
    "state": "authorized",
    "integration_state": "configured",
    "auth_type": "oauth2",
    "oauth_grant_type": "authorization_code",
    "enabled": true,
    "website": "https://www.salesforce.com",
    "icon": "https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png",
    "logo": "https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg",
    "authorize_url": "https://unify.apideck.com/vault/authorize/salesforce/<application-id>?state=<state>",
    "revoke_url": "https://unify.apideck.com/vault/revoke/salesforce/<application-id>?state=<state>",
    "settings": {
      "instance_url": "https://eu28.salesforce.com",
      "api_key": "12345xxxxxx"
    },
    "metadata": {
      "account": {
        "name": "My Company",
        "id": "c01458a5-7276-41ce-bc19-639906b0450a"
      },
      "plan": "enterprise"
    },
    "form_fields": [
      {
        "id": "instance_url",
        "label": "Instance url",
        "value": "https://eu28.salesforce.com",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": false
      },
      {
        "id": "api_key",
        "label": "API Key",
        "value": "123455677",
        "placeholder": "",
        "mask": false,
        "type": "text",
        "required": true,
        "disabled": false,
        "custom_field": false,
        "sensitive": true
      }
    ],
    "configuration": [
      {
        "resource": "leads",
        "defaults": [
          {
            "target": "custom_fields",
            "id": "ProductInterest",
            "options": [
              {
                "label": "General Channel",
                "value": "general"
              }
            ],
            "value": "GC5000 series"
          }
        ]
      }
    ],
    "configurable_resources": [
      "opportunities",
      "companies",
      "contacts",
      "leads"
    ],
    "resource_schema_support": [
      "leads"
    ],
    "resource_settings_support": [
      "leads"
    ],
    "settings_required_for_authorization": [
      "client_id",
      "client_secret"
    ],
    "subscriptions": [
      {
        "downstream_id": "5f5f5f5f5f5f5f5f5f5f5f5f",
        "unify_event_types": [
          "crm.contact.created"
        ],
        "downstream_event_types": [
          "contacts.CREATED"
        ],
        "execute_url": "https://unify.apideck.com/webhook/w/{lookupIdToken}/{serviceId}?e={downstreamEventType}",
        "created_at": "2020-10-01T12:00:00.000Z"
      }
    ],
    "has_guide": true,
    "custom_mappings": [
      {
        "id": "hris+employees+first_aid_training",
        "label": "First Aid Training",
        "description": "First Aid Training completed after 2019-01-01",
        "value": "$.root.training.first_aid",
        "key": "first_aid_training",
        "custom_field": true,
        "consumer_id": "test_user_id",
        "example": "Some value"
      }
    ],
    "consent_state": "granted",
    "consents": [
      {
        "id": "con_1234567890",
        "created_at": "2025-04-15T14:30:00Z",
        "granted": true,
        "resources": {
          "hris.employees": {
            "id": {
              "read": true,
              "write": false
            },
            "first_name": {
              "read": true,
              "write": true
            },
            "last_name": {
              "read": true,
              "write": true
            },
            "email": {
              "read": true,
              "write": true
            },
            "addresses[].street": {
              "read": true,
              "write": false
            },
            "addresses[].city": {
              "read": true,
              "write": false
            },
            "employment.job_title": {
              "read": true,
              "write": true
            },
            "custom_fields[].employee_number": {
              "read": true,
              "write": false
            }
          },
          "hris.departments": {
            "id": {
              "read": true,
              "write": false
            },
            "name": {
              "read": true,
              "write": true
            },
            "code": {
              "read": true,
              "write": false
            }
          }
        }
      }
    ],
    "latest_consent": {
      "id": "con_1234567890",
      "created_at": "2025-04-15T14:30:00Z",
      "granted": true,
      "resources": {
        "hris.employees": {
          "id": {
            "read": true,
            "write": false
          },
          "first_name": {
            "read": true,
            "write": true
          },
          "last_name": {
            "read": true,
            "write": true
          },
          "email": {
            "read": true,
            "write": true
          },
          "addresses[].street": {
            "read": true,
            "write": false
          },
          "addresses[].city": {
            "read": true,
            "write": false
          },
          "employment.job_title": {
            "read": true,
            "write": true
          },
          "custom_fields[].employee_number": {
            "read": true,
            "write": false
          }
        },
        "hris.departments": {
          "id": {
            "read": true,
            "write": false
          },
          "name": {
            "read": true,
            "write": true
          },
          "code": {
            "read": true,
            "write": false
          }
        }
      }
    },
    "application_data_scopes": {
      "enabled": true,
      "updated_at": "2025-04-15T14:30:00Z",
      "resources": {
        "hris.employees": {
          "id": {
            "read": true,
            "write": false
          },
          "first_name": {
            "read": true,
            "write": true
          },
          "last_name": {
            "read": true,
            "write": true
          },
          "email": {
            "read": true,
            "write": true
          },
          "addresses[].street": {
            "read": true,
            "write": false
          },
          "addresses[].city": {
            "read": true,
            "write": false
          },
          "employment.job_title": {
            "read": true,
            "write": true
          },
          "custom_fields[].employee_number": {
            "read": true,
            "write": false
          }
        },
        "hris.departments": {
          "id": {
            "read": true,
            "write": false
          },
          "name": {
            "read": true,
            "write": true
          },
          "code": {
            "read": true,
            "write": false
          }
        }
      }
    },
    "health": "ok",
    "credentials_expire_at": 1730172800000,
    "last_refresh_failed_at": 1730000000000,
    "last_downstream_error_at": 1730000000000,
    "created_at": 1615563533390,
    "updated_at": 1616662325753
  }
}