Update an installation object

Updates a single object’s configuration within an installation using JSON Patch syntax.

PATCH /projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content

Update an installation object

cURL

curl --request PATCH \
  --url https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "groupRef": "group-123",
  "action": "read",
  "changes": [
    {
      "op": "replace",
      "path": "/schedule",
      "value": "*/10 * * * *"
    },
    {
      "op": "add",
      "path": "/selectedFields/phone",
      "value": true
    },
    {
      "op": "remove",
      "path": "/selectedFields/billingcity"
    }
  ]
}
'

import requests

url = "https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content"

payload = {
    "groupRef": "group-123",
    "action": "read",
    "changes": [
        {
            "op": "replace",
            "path": "/schedule",
            "value": "*/10 * * * *"
        },
        {
            "op": "add",
            "path": "/selectedFields/phone",
            "value": True
        },
        {
            "op": "remove",
            "path": "/selectedFields/billingcity"
        }
    ]
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    groupRef: 'group-123',
    action: 'read',
    changes: [
      {op: 'replace', path: '/schedule', value: '*/10 * * * *'},
      {op: 'add', path: '/selectedFields/phone', value: true},
      {op: 'remove', path: '/selectedFields/billingcity'}
    ]
  })
};

fetch('https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content', 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}/integrations/{integrationId}/objects/{objectName}/config-content",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'groupRef' => 'group-123',
    'action' => 'read',
    'changes' => [
        [
                'op' => 'replace',
                'path' => '/schedule',
                'value' => '*/10 * * * *'
        ],
        [
                'op' => 'add',
                'path' => '/selectedFields/phone',
                'value' => true
        ],
        [
                'op' => 'remove',
                'path' => '/selectedFields/billingcity'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content"

	payload := strings.NewReader("{\n  \"groupRef\": \"group-123\",\n  \"action\": \"read\",\n  \"changes\": [\n    {\n      \"op\": \"replace\",\n      \"path\": \"/schedule\",\n      \"value\": \"*/10 * * * *\"\n    },\n    {\n      \"op\": \"add\",\n      \"path\": \"/selectedFields/phone\",\n      \"value\": true\n    },\n    {\n      \"op\": \"remove\",\n      \"path\": \"/selectedFields/billingcity\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"groupRef\": \"group-123\",\n  \"action\": \"read\",\n  \"changes\": [\n    {\n      \"op\": \"replace\",\n      \"path\": \"/schedule\",\n      \"value\": \"*/10 * * * *\"\n    },\n    {\n      \"op\": \"add\",\n      \"path\": \"/selectedFields/phone\",\n      \"value\": true\n    },\n    {\n      \"op\": \"remove\",\n      \"path\": \"/selectedFields/billingcity\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/objects/{objectName}/config-content")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"groupRef\": \"group-123\",\n  \"action\": \"read\",\n  \"changes\": [\n    {\n      \"op\": \"replace\",\n      \"path\": \"/schedule\",\n      \"value\": \"*/10 * * * *\"\n    },\n    {\n      \"op\": \"add\",\n      \"path\": \"/selectedFields/phone\",\n      \"value\": true\n    },\n    {\n      \"op\": \"remove\",\n      \"path\": \"/selectedFields/billingcity\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

200

{
  "id": "<string>",
  "projectId": "project-456",
  "integrationId": "<string>",
  "healthStatus": "healthy",
  "connection": {
    "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": {}
  },
  "createTime": "2023-11-07T05:31:56Z",
  "createdBy": "consumer:consumer-123",
  "config": {
    "id": "config-123",
    "revisionId": "revision-123",
    "createTime": "2023-11-07T05:31:56Z",
    "createdBy": "builder:builder-123",
    "content": {
      "provider": "hubspot",
      "read": {
        "objects": {}
      },
      "write": {
        "objects": {}
      },
      "proxy": {
        "enabled": true
      },
      "subscribe": {
        "objects": {}
      }
    }
  },
  "group": {
    "groupRef": "group-123",
    "groupName": "Super Customer",
    "projectId": "project-456",
    "createTime": "2023-07-13T21:34:44.816354Z",
    "updateTime": "2023-07-13T21:34:44.816354Z"
  },
  "lastOperationStatus": "success",
  "updateTime": "2023-11-07T05:31:56Z"
}

{
  "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": "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

APIKeyHeaderBearer

X-Api-Key · string · header · required

Path Parameters

projectIdOrName · string · required

The Ampersand project ID or project name.

integrationId · string · required

The integration ID.

objectName · string · required

The object name whose config content will be patched. Must match an object name defined in the integration's manifest for the specified action type (read, subscribe, or write). Common examples include: account, contact, lead, opportunity (for Salesforce), deal, company (for HubSpot), etc.

Body

application/json

Option 1

Option 2

groupRef · string · required

The ID of the user group that has access to this installation. Either groupRef or installationId must be provided.

Example:

"group-123"

action · enum<string> · required

The action type for the object config (read, subscribe, or write).

Available options: read, subscribe, write

Example:

"read"

changes · JSON Patch Operation · object[] · required

Array of JSON Patch operations to apply.

Minimum array length: 1

Show child attributes

Example:

[
  {
    "op": "replace",
    "path": "/schedule",
    "value": "*/10 * * * *"
  },
  {
    "op": "add",
    "path": "/selectedFields/phone",
    "value": true
  },
  {
    "op": "remove",
    "path": "/selectedFields/billingcity"
  }
]

Response

200

application/json

The updated installation

id · string · required

The installation ID.

projectId · string · required

The Ampersand project ID.

Example:

"project-456"

integrationId · string · required

The integration ID.

healthStatus · enum<string> · required

The health status of the installation.

Available options: healthy, unhealthy

Example:

"healthy"

connection · Connection · object · required

Show child attributes

createTime · string<date-time> · required

The time the installation was created.

createdBy · string · required

The person who did the installation, in the format of "consumer:{consumer-id}".

Example:

"consumer:consumer-123"

config · Config · object · required

Show child attributes

group · Group · object

Show child attributes

lastOperationStatus · enum<string>

The status of the latest operation for this installation.

Available options: success, failure, in_progress

Example:

"success"

updateTime · string<date-time>

The time the installation was last updated with a new config.