Sign in
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
  }
}

Changes

Changed in 5 of the 66 revisions of this API.410

  • fefba4c4b4492See the full diff
    • ○

      added the new optional request property form_fields/items/options_fetch_error

      new-optional-request-property

    • ○

      added the optional property data/form_fields/items/options_fetch_error to the response with the 200 status

      response-optional-property-added

  • 3f9c2f2b6d921See the full diff
    • ○

      added the optional property data/metadata/company_id to the response with the 200 status

      response-optional-property-added

  • 3dc2f3a25b4012See the full diff
    • ●

      added the new degraded enum value to the data/health response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new degraded enum value to the request property health

      request-property-enum-value-added

    • ○

      added the optional property data/last_downstream_error_at to the response with the 200 status

      response-optional-property-added

  • cfde3408f52711See the full diff
    • ●

      added the new pending_confirmation enum value to the data/health response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new pending_confirmation enum value to the request property health

      request-property-enum-value-added

  • 79ff7820cc6f24See the full diff
    • ●

      removed the optional property data/last_downstream_error_at from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property data/metadata/company_id from the response with the 200 status

      response-optional-property-removed

    • ○

      removed the enum value degraded of the request read-only property health

      request-read-only-property-enum-value-removed

    • ○

      removed the enum value pending_confirmation of the request read-only property health

      request-read-only-property-enum-value-removed

    • ○

      removed the degraded enum value from the data/health response property for the response status 200

      response-property-enum-value-removed

    • ○

      removed the pending_confirmation enum value from the data/health response property for the response status 200

      response-property-enum-value-removed

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog