Authentication
WRITE API
- Write
READ API
- Read
PLATFORM API
- OAuth
- Project
- Provider App
- Integration
- Revision
- Installation
- Objects & Fields
- Operation
- Provider
- API Key
- Connection
- Group
- Consumer
- Destination
- Upload URL
- Org
- User
- Billing Account
Create a new installation
curl --request POST \
--url https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/installations \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '{
"groupRef": "<string>",
"connectionId": "<string>",
"config": {
"revisionId": "<string>",
"createdBy": "api:create-installation",
"content": {
"provider": "salesforce",
"read": {
"objects": {}
},
"write": {
"objects": {}
},
"proxy": {
"enabled": true
}
}
}
}'{
"id": "installation-123",
"projectId": "project-456",
"integrationId": "integration-123",
"group": {
"groupRef": "group-123",
"groupName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z"
},
"healthStatus": "healthy",
"connection": {
"id": "connection-123",
"projectId": "project-456",
"provider": "salesforce",
"providerApp": {
"id": "provider-app-123",
"projectId": "project-456",
"externalRef": "external-id-123",
"provider": "salesforce",
"clientId": "client-id-123",
"scopes": [
[
"oauth",
"offline",
"crm.read"
]
],
"createTime": "2023-11-07T05:31:56Z",
"updateTime": "2023-11-07T05:31:56Z"
},
"group": {
"groupRef": "group-123",
"groupName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z"
},
"consumer": {
"consumerRef": "consumer-123",
"consumerName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z"
},
"providerWorkspaceRef": "provider-workspace-123",
"providerConsumerRef": "provider-consumer-123",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z",
"authScheme": "oauth2/authorizationCode",
"status": "working",
"oauth2AuthorizationCode": {
"accessToken": {
"token": "<string>",
"issuedAt": "2024-04-22T18:55:28.456076Z",
"expiresAt": "2024-10-22T18:55:28.456076Z"
},
"refreshToken": {
"token": "<string>",
"issuedAt": "2024-04-22T18:55:28.456076Z",
"expiresAt": "2024-10-22T18:55:28.456076Z"
},
"scopes": [
"<string>"
]
},
"apiKey": "api-key-123"
},
"createTime": "2023-11-07T05:31:56Z",
"createdBy": "consumer:consumer-123",
"updateTime": "2023-11-07T05:31:56Z",
"config": {
"id": "config-123",
"revisionId": "revision-123",
"createTime": "2023-11-07T05:31:56Z",
"createdBy": "builder:builder-123",
"content": {
"provider": "salesforce",
"read": {
"objects": {}
},
"write": {
"objects": {}
},
"proxy": {
"enabled": true
}
}
}
}Authorizations
Body
The ID of the user group that has access to this installation.
The config of the installation.
The SaaS API that we are integrating with.
"salesforce"
The ID of the revision that this config is based on. If omitted, the latest revision is assumed.
The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".
The ID of the SaaS connection tied to this installation. If omitted the default connection for this group will be used.
Response
The installation ID.
"installation-123"
The Ampersand project ID.
"project-456"
The integration ID.
"integration-123"
The health status of the installation ("healthy", "unhealthy").
"healthy"
The connection ID.
"connection-123"
The Ampersand project ID.
"project-456"
The SaaS provider that this Connection is for.
"salesforce"
The ID of the user group that has access to this installation.
"group-123"
The name of the user group that has access to this installation.
"Super Customer"
The Ampersand project ID.
"project-456"
The time the group was created.
"2023-07-13T21:34:44.816Z"
The time the group was last updated.
"2023-07-13T21:34:44.816Z"
The consumer reference.
"consumer-123"
The name of the consumer.
"Super Customer"
The Ampersand project ID.
"project-456"
The time the consumer was created.
"2023-07-13T21:34:44.816Z"
The time the consumer was last updated.
"2023-07-13T21:34:44.816Z"
The time the connection was created.
"2023-07-13T21:34:44.816Z"
The authentication scheme used for this connection.
none, apiKey, basic, oauth2/authorizationCode, oauth2/authorizationCodePKCE, oauth2/clientCredentials, oauth2/password "oauth2/authorizationCode"
The status of the connection.
created, working, bad_credentials "working"
The provider app ID.
"provider-app-123"
The Ampersand project ID.
"project-456"
The SaaS provider that this app connects to.
"salesforce"
The OAuth client ID for this app.
"client-id-123"
The time the provider app was created.
The ID used by the provider to identify the app (optional).
"external-id-123"
The OAuth scopes for this app.
The time the provider app was updated.
If available, the identifier for the provider workspace (e.g. "salesforce-instance-domain")
"provider-workspace-123"
If available, the ID that Salesforce/Hubspot uses to identify this user (e.g. Salesforce has IDs in the form of https://login.salesforce.com/id/00D4x0000019CQTEA2/0054x000000orJ4AA)
"provider-consumer-123"
The time the connection was last updated.
"2023-07-13T21:34:44.816Z"
The access token for the connection.
The refresh token to use for the connection.
The scopes for the tokens.
The API key used while making the connection.
"api-key-123"
The time the integration was first installed.
The person who did the installation, in the format of "consumer:{consumer-id}".
"consumer:consumer-123"
The config ID.
"config-123"
The ID of the revision that this config is based on.
"revision-123"
The time the config was created.
The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}".
"builder:builder-123"
The SaaS API that we are integrating with.
"salesforce"
The ID of the user group that has access to this installation.
"group-123"
The name of the user group that has access to this installation.
"Super Customer"
The Ampersand project ID.
"project-456"
The time the group was created.
"2023-07-13T21:34:44.816Z"
The time the group was last updated.
"2023-07-13T21:34:44.816Z"
The time the installation was last updated with a new config.
Was this page helpful?
curl --request POST \
--url https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/installations \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '{
"groupRef": "<string>",
"connectionId": "<string>",
"config": {
"revisionId": "<string>",
"createdBy": "api:create-installation",
"content": {
"provider": "salesforce",
"read": {
"objects": {}
},
"write": {
"objects": {}
},
"proxy": {
"enabled": true
}
}
}
}'{
"id": "installation-123",
"projectId": "project-456",
"integrationId": "integration-123",
"group": {
"groupRef": "group-123",
"groupName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z"
},
"healthStatus": "healthy",
"connection": {
"id": "connection-123",
"projectId": "project-456",
"provider": "salesforce",
"providerApp": {
"id": "provider-app-123",
"projectId": "project-456",
"externalRef": "external-id-123",
"provider": "salesforce",
"clientId": "client-id-123",
"scopes": [
[
"oauth",
"offline",
"crm.read"
]
],
"createTime": "2023-11-07T05:31:56Z",
"updateTime": "2023-11-07T05:31:56Z"
},
"group": {
"groupRef": "group-123",
"groupName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z"
},
"consumer": {
"consumerRef": "consumer-123",
"consumerName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z"
},
"providerWorkspaceRef": "provider-workspace-123",
"providerConsumerRef": "provider-consumer-123",
"createTime": "2023-07-13T21:34:44.816Z",
"updateTime": "2023-07-13T21:34:44.816Z",
"authScheme": "oauth2/authorizationCode",
"status": "working",
"oauth2AuthorizationCode": {
"accessToken": {
"token": "<string>",
"issuedAt": "2024-04-22T18:55:28.456076Z",
"expiresAt": "2024-10-22T18:55:28.456076Z"
},
"refreshToken": {
"token": "<string>",
"issuedAt": "2024-04-22T18:55:28.456076Z",
"expiresAt": "2024-10-22T18:55:28.456076Z"
},
"scopes": [
"<string>"
]
},
"apiKey": "api-key-123"
},
"createTime": "2023-11-07T05:31:56Z",
"createdBy": "consumer:consumer-123",
"updateTime": "2023-11-07T05:31:56Z",
"config": {
"id": "config-123",
"revisionId": "revision-123",
"createTime": "2023-11-07T05:31:56Z",
"createdBy": "builder:builder-123",
"content": {
"provider": "salesforce",
"read": {
"objects": {}
},
"write": {
"objects": {}
},
"proxy": {
"enabled": true
}
}
}
}