Update an installation

Update an installation. NOTE: Updating an installation with the Subscribe action typically takes 1–2 minutes, but it may take up to 10 minutes to take effect due to delays in the provider’s system.

PATCH /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}

Update an installation

cURL

curl --request PATCH \
  --url https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "updateMask": [
    "config.content.read.objects.contacts",
    "config.content.write.objects.leads"
  ],
  "installation": {
    "connectionId": "connection-123",
    "config": {
      "revisionId": "<string>",
      "createdBy": "<string>",
      "content": {
        "provider": "hubspot",
        "read": {
          "objects": {}
        },
        "write": {
          "objects": {}
        },
        "proxy": {
          "enabled": true
        }
      }
    }
  }
}
'

import requests

url = "https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}"

payload = {
    "updateMask": ["config.content.read.objects.contacts", "config.content.write.objects.leads"],
    "installation": {
        "connectionId": "connection-123",
        "config": {
            "revisionId": "<string>",
            "createdBy": "<string>",
            "content": {
                "provider": "hubspot",
                "read": { "objects": {} },
                "write": { "objects": {} },
                "proxy": { "enabled": True }
            }
        }
    }
}
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({
    updateMask: ['config.content.read.objects.contacts', 'config.content.write.objects.leads'],
    installation: {
      connectionId: 'connection-123',
      config: {
        revisionId: '<string>',
        createdBy: '<string>',
        content: {
          provider: 'hubspot',
          read: {objects: {}},
          write: {objects: {}},
          proxy: {enabled: true}
        }
      }
    }
  })
};

fetch('https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}', 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}/installations/{installationId}",
  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([
    'updateMask' => [
        'config.content.read.objects.contacts',
        'config.content.write.objects.leads'
    ],
    'installation' => [
        'connectionId' => 'connection-123',
        'config' => [
                'revisionId' => '<string>',
                'createdBy' => '<string>',
                'content' => [
                                'provider' => 'hubspot',
                                'read' => [
                                                                'objects' => [
                                                                                                                                
                                                                ]
                                ],
                                'write' => [
                                                                'objects' => [
                                                                                                                                
                                                                ]
                                ],
                                'proxy' => [
                                                                'enabled' => true
                                ]
                ]
        ]
    ]
  ]),
  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}/installations/{installationId}"

	payload := strings.NewReader("{\n  \"updateMask\": [\n    \"config.content.read.objects.contacts\",\n    \"config.content.write.objects.leads\"\n  ],\n  \"installation\": {\n    \"connectionId\": \"connection-123\",\n    \"config\": {\n      \"revisionId\": \"<string>\",\n      \"createdBy\": \"<string>\",\n      \"content\": {\n        \"provider\": \"hubspot\",\n        \"read\": {\n          \"objects\": {}\n        },\n        \"write\": {\n          \"objects\": {}\n        },\n        \"proxy\": {\n          \"enabled\": true\n        }\n      }\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}/installations/{installationId}")
  .header("X-Api-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"updateMask\": [\n    \"config.content.read.objects.contacts\",\n    \"config.content.write.objects.leads\"\n  ],\n  \"installation\": {\n    \"connectionId\": \"connection-123\",\n    \"config\": {\n      \"revisionId\": \"<string>\",\n      \"createdBy\": \"<string>\",\n      \"content\": {\n        \"provider\": \"hubspot\",\n        \"read\": {\n          \"objects\": {}\n        },\n        \"write\": {\n          \"objects\": {}\n        },\n        \"proxy\": {\n          \"enabled\": true\n        }\n      }\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withampersand.com/v1/projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}")

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  \"updateMask\": [\n    \"config.content.read.objects.contacts\",\n    \"config.content.write.objects.leads\"\n  ],\n  \"installation\": {\n    \"connectionId\": \"connection-123\",\n    \"config\": {\n      \"revisionId\": \"<string>\",\n      \"createdBy\": \"<string>\",\n      \"content\": {\n        \"provider\": \"hubspot\",\n        \"read\": {\n          \"objects\": {}\n        },\n        \"write\": {\n          \"objects\": {}\n        },\n        \"proxy\": {\n          \"enabled\": true\n        }\n      }\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"
        ]
      ],
      "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.

installationId · string · required

The Ampersand installation ID.

Body

application/json

updateMask · string[] · required

Array of field paths specifying which fields to update. Allowed values include:

• connectionId
• config.createdBy
• config.content.read.objects.OBJECT_NAME
• config.content.write.objects.OBJECT_NAME
• config.content.write.objects
• config.content.subscribe.objects.OBJECT_NAME
• config.content.subscribe.objects
• config.content.proxy.enabled

OBJECT_NAME means you can specify any object name.

Example:

[
  "config.content.read.objects.contacts",
  "config.content.write.objects.leads"
]

installation · object · required

The installation fields to update. (You only need to include the fields you'd like to update, which are specified in the update masks. The rest will be ignored.)

Show child attributes

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 · string · required

The health status of the installation ("healthy", "unhealthy").

Example:

"healthy"

connection · Connection · object · required

Show child attributes

createTime · string<date-time> · required

The time the integration was first installed.

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.