curl --request GET \
--url https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId} \
--header 'X-Api-Key: <api-key>'import requests
url = "https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}"
headers = {"X-Api-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};
fetch('https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Api-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}")
.header("X-Api-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "connection-123",
"projectId": "project-456",
"provider": "salesforce",
"group": {
"groupRef": "group-123",
"groupName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816354Z",
"updateTime": "2023-07-13T21:34:44.816354Z"
},
"consumer": {
"consumerRef": "consumer-123",
"consumerName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816354Z",
"updateTime": "2023-07-13T21:34:44.816354Z"
},
"createTime": "2023-07-13T21:34:44.816354Z",
"authScheme": "oauth2/authorizationCode",
"status": "working",
"providerApp": {
"id": "provider-app-123",
"projectId": "project-456",
"provider": "salesforce",
"clientId": "client-id-123",
"createTime": "2023-11-07T05:31:56Z",
"externalRef": "external-id-123",
"scopes": [
[
"oauth",
"offline",
"crm.read"
]
],
"metadata": {
"authQueryParams": {
"optional_scope": [
"automation.sequences.read"
]
},
"providerParams": {
"packageInstallURL": "https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789",
"gcpProjectId": "my-gcp-project",
"gcpPubSubTopicName": "my-topic"
}
},
"updateTime": "2023-11-07T05:31:56Z"
},
"providerWorkspaceRef": "provider-workspace-123",
"providerConsumerRef": "provider-consumer-123",
"updateTime": "2023-07-13T21:34:44.816354Z",
"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",
"providerMetadata": {}
}{
"type": "about:blank",
"href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
"title": "Bad Request",
"status": 400,
"detail": "The input message is incorrect",
"instance": "123456-1234-1235-4567489798",
"issues": [
{
"type": "about:blank",
"detail": "exampleNumericProperty should be numeric",
"in": "path",
"name": "exampleNumericProperty",
"value": "abc"
},
{
"type": "about:blank",
"title": "Input isn't valid with respect to schema",
"detail": "examplePropertyWithPattern a2345678901 doesn't match pattern '^\\d{11}$'",
"in": "body",
"name": "items[0].examplePropertyWithPattern",
"value": "a2345678901"
}
]
}{
"type": "urn:problem-type:exampleOrganization:exampleProblem",
"href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
"title": "Description of the type of problem that occurred",
"status": 400,
"detail": "Description of specific occurrence of the problem",
"instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
}Get a connection
curl --request GET \
--url https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId} \
--header 'X-Api-Key: <api-key>'import requests
url = "https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}"
headers = {"X-Api-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-Api-Key': '<api-key>'}};
fetch('https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Api-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}")
.header("X-Api-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withampersand.com/v1/projects/{projectIdOrName}/connections/{connectionId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Api-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "connection-123",
"projectId": "project-456",
"provider": "salesforce",
"group": {
"groupRef": "group-123",
"groupName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816354Z",
"updateTime": "2023-07-13T21:34:44.816354Z"
},
"consumer": {
"consumerRef": "consumer-123",
"consumerName": "Super Customer",
"projectId": "project-456",
"createTime": "2023-07-13T21:34:44.816354Z",
"updateTime": "2023-07-13T21:34:44.816354Z"
},
"createTime": "2023-07-13T21:34:44.816354Z",
"authScheme": "oauth2/authorizationCode",
"status": "working",
"providerApp": {
"id": "provider-app-123",
"projectId": "project-456",
"provider": "salesforce",
"clientId": "client-id-123",
"createTime": "2023-11-07T05:31:56Z",
"externalRef": "external-id-123",
"scopes": [
[
"oauth",
"offline",
"crm.read"
]
],
"metadata": {
"authQueryParams": {
"optional_scope": [
"automation.sequences.read"
]
},
"providerParams": {
"packageInstallURL": "https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789",
"gcpProjectId": "my-gcp-project",
"gcpPubSubTopicName": "my-topic"
}
},
"updateTime": "2023-11-07T05:31:56Z"
},
"providerWorkspaceRef": "provider-workspace-123",
"providerConsumerRef": "provider-consumer-123",
"updateTime": "2023-07-13T21:34:44.816354Z",
"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",
"providerMetadata": {}
}{
"type": "about:blank",
"href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
"title": "Bad Request",
"status": 400,
"detail": "The input message is incorrect",
"instance": "123456-1234-1235-4567489798",
"issues": [
{
"type": "about:blank",
"detail": "exampleNumericProperty should be numeric",
"in": "path",
"name": "exampleNumericProperty",
"value": "abc"
},
{
"type": "about:blank",
"title": "Input isn't valid with respect to schema",
"detail": "examplePropertyWithPattern a2345678901 doesn't match pattern '^\\d{11}$'",
"in": "body",
"name": "items[0].examplePropertyWithPattern",
"value": "a2345678901"
}
]
}{
"type": "urn:problem-type:exampleOrganization:exampleProblem",
"href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types",
"title": "Description of the type of problem that occurred",
"status": 400,
"detail": "Description of specific occurrence of the problem",
"instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000"
}Authorizations
Path Parameters
The Ampersand project ID or project name.
Query Parameters
Whether to include credentials for oauth2AuthorizationCode in the response. If true, accessToken and scopes are included. To include refreshToken as well, set includeRefreshToken to true. Default is false.
Whether to include refreshToken for oauth2AuthorizationCode credentials in the response (along with accessToken and scopes). If true, the includeCreds query parameter will be ignored. Default is false.
Whether to refresh the access token. If value is ifExpired, the access token will be refreshed only if it has expired. If value is force, the access token will be refreshed regardless of its expiration.
force, ifExpired Response
Connection
The connection ID.
"connection-123"
The Ampersand project ID.
"project-456"
The SaaS provider that this Connection is for.
"salesforce"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
The time the connection was created.
"2023-07-13T21:34:44.816354Z"
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: The connection has just been created or the access token was just refreshed.working: The connection has successfully been used to make a request.bad_credentials: The connection encountered credential-related issues when making a request, or when attempting to refresh the access token.
created, working, bad_credentials "working"
Show child attributes
Show child attributes
If available, the identifier for the provider workspace (e.g. the Salesforce subdomain)
"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.816354Z"
Show child attributes
Show child attributes
The API key used while making the connection.
"api-key-123"
Show child attributes
Show child attributes
Was this page helpful?

