Move Integration API
The Move Integration API reassigns an existing integration to another profile in the same project. It uses PATCH {{API_BASE_URL}}/v1/connect/integrations/{id}, where {id} is the Integration ID. Passing profileId=null leaves the integration unassigned. OAuth credentials and existing posts are unchanged by this operation.
Move Integration API — endpoint summary
This endpoint reassigns an existing integration to another profile in the same project. The request uses the PATCH method with the exact path /v1/connect/integrations/{id}, prefixed by {{API_BASE_URL}} as the origin. The {id} path segment is the Integration ID of the integration to move. Moving an integration does not change its OAuth credentials, and existing posts are unchanged.
Authorization
Authorization uses an access key supplied in the x-access-key header. Send the token as the header value, for example x-access-key: <token>. The request body must be sent as application/json.
Path Parameters
The path contains one required parameter. The id parameter is a string and identifies the integration by its Integration ID. Replace the {id} segment in {{API_BASE_URL}}/v1/connect/integrations/{id} with that string value. Do not add query parameters, because none are documented for this endpoint.
Request Body
The request body is a JSON object with one required field. The profileId field accepts a string or null. A string value is the destination profile ID and reassigns the integration to that profile. Passing null removes the integration from its current profile and leaves it unassigned. The field is required in both cases, so omitting it is not equivalent to passing null. See the decision table and the worked examples titled Reassign an integration to another profile and Unassign an integration with profileId null.
Response Body
The response body is JSON. A 200 response contains success set to true and an integration object. The integration object includes fields such as id, platform, platformUserId, username, displayName, profileUrl, imageUrl, platformMetadata, profileId, profileName, appId, app, byok, authStatus, authFailureReason, insightsReadable, and createdAt. Fields including platformUserId, authStatus, and insightsReadable should be read from the returned object rather than assumed from the request. The 400, 404, and 409 responses each contain an error string field. See the field map and status matrix tables for the exact documented shapes.
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Integration ID |
Exact documented path parameter for PATCH {{API_BASE_URL}}/v1/connect/integrations/{id}.
| Field | Type | Required | Description |
|---|---|---|---|
| profileId | string | null | Yes | Destination profile ID. Pass null to remove the integration from its current profile. |
Exact documented request body for application/json.
| profileId value | Effect | OAuth credentials and existing posts |
|---|---|---|
| Destination profile ID string | Reassigns the integration to another profile in the same project | Unchanged |
| null | Leaves the integration unassigned | Unchanged |
Decision table distinguishing the two documented profileId values.
| Field | Type | Description |
|---|---|---|
| id | string | Integration identifier |
| platform | string | Platform identifier; example value is twitter |
| platformUserId | string | Platform user identifier |
| username | string | Username |
| displayName | string | Display name |
| profileUrl | string | Profile URL |
| imageUrl | string | Image URL |
| platformMetadata | object | Platform metadata object |
| profileId | string | Assigned profile ID in 200 example |
| profileName | string | Assigned profile name |
| appId | string | App identifier |
| app | object | Nested app object with id, name, and imageUrl |
| byok | boolean | Bring-your-own-key flag |
| authStatus | string | Authentication status; example value is active |
| authFailureReason | string | Authentication failure reason; example value is token_expired |
| insightsReadable | boolean | Whether insights are readable |
| createdAt | string | Creation timestamp; example value is 2019-08-24T14:15:22Z |
Field map for the integration object in the 200 response, preserving documented names and example types. profileId is shown as string as in the 200 example, distinct from request body profileId string|null.
| Status | Content type | Response shape |
|---|---|---|
| 200 | application/json | { success: true, integration: { ... } } |
| 400 | application/json | { error: string } |
| 404 | application/json | { error: string } |
| 409 | application/json | { error: string } |
Only documented response shapes are listed; specific trigger conditions for 400, 404, and 409 are not defined in the source and are not invented here.
Frequently asked questions
How do I move an integration to another profile?
Send PATCH to {{API_BASE_URL}}/v1/connect/integrations/{id} with the x-access-key header and a JSON body containing the required profileId field. Use a destination profile ID string to reassign, or null to unassign.
How do I unassign an integration from its current profile?
Pass profileId as null in the request body. The integration is left unassigned, while OAuth credentials and existing posts are unchanged.
What response shapes should I handle?
A 200 response returns success set to true and an integration object. The 400, 404, and 409 responses each return an object with a required error string field.
curl -X PATCH "{{API_BASE_URL}}/v1/connect/integrations/{id}" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"profileId": "<destination_profile_id>"
}'curl -X PATCH "{{API_BASE_URL}}/v1/connect/integrations/{id}" \
-H "Content-Type: application/json" \
-H "x-access-key: <token>" \
-d '{
"profileId": null
}'{
"success": true,
"integration": {
"id": "string",
"platform": "twitter",
"platformUserId": "string",
"username": "string",
"displayName": "string",
"profileUrl": "http://example.com",
"imageUrl": "http://example.com",
"platformMetadata": {},
"profileId": "string",
"profileName": "string",
"appId": "string",
"app": {
"id": "string",
"name": "string",
"imageUrl": "string"
},
"byok": true,
"authStatus": "active",
"authFailureReason": "token_expired",
"insightsReadable": true,
"createdAt": "2019-08-24T14:15:22Z"
}
}| Scope | Field | Type | Type reference | Required | Description |
|---|---|---|---|---|---|
| id#1 | id | string | __0 | Yes | Integration ID |
| body#2 | body | object | __0 | Yes | |
| body#2 | body.profileId | string | null | __1 | Yes | Destination profile ID. Pass null to remove the integration from its current profile. |
| body#2 | body.profileId[variant1] | string | __1_type:string | Destination profile ID. Pass null to remove the integration from its current profile. | |
| body#2 | body.profileId[variant2] | null | __1_type:null | Destination profile ID. Pass null to remove the integration from its current profile. | |
| response#3 | response | object | __0 | ||
| response#3 | response.error | string | __1 | Yes |