Skip to content

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.

Path parameters
FieldTypeRequiredDescription
idstringYesIntegration ID

Exact documented path parameter for PATCH {{API_BASE_URL}}/v1/connect/integrations/{id}.

Request body fields
FieldTypeRequiredDescription
profileIdstring | nullYesDestination profile ID. Pass null to remove the integration from its current profile.

Exact documented request body for application/json.

Reassign versus unassign decision
profileId valueEffectOAuth credentials and existing posts
Destination profile ID stringReassigns the integration to another profile in the same projectUnchanged
nullLeaves the integration unassignedUnchanged

Decision table distinguishing the two documented profileId values.

200 integration object field map
FieldTypeDescription
idstringIntegration identifier
platformstringPlatform identifier; example value is twitter
platformUserIdstringPlatform user identifier
usernamestringUsername
displayNamestringDisplay name
profileUrlstringProfile URL
imageUrlstringImage URL
platformMetadataobjectPlatform metadata object
profileIdstringAssigned profile ID in 200 example
profileNamestringAssigned profile name
appIdstringApp identifier
appobjectNested app object with id, name, and imageUrl
byokbooleanBring-your-own-key flag
authStatusstringAuthentication status; example value is active
authFailureReasonstringAuthentication failure reason; example value is token_expired
insightsReadablebooleanWhether insights are readable
createdAtstringCreation 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.

Response status matrix
StatusContent typeResponse shape
200application/json{ success: true, integration: { ... } }
400application/json{ error: string }
404application/json{ error: string }
409application/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.

Reassign an integration to another profile
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>"
  }'
Unassign an integration with profileId null
curl -X PATCH "{{API_BASE_URL}}/v1/connect/integrations/{id}" \
  -H "Content-Type: application/json" \
  -H "x-access-key: <token>" \
  -d '{
    "profileId": null
  }'
200 success response example
{
  "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"
  }
}
Interface fields
ScopeFieldTypeType referenceRequiredDescription
id#1idstring__0YesIntegration ID
body#2bodyobject__0Yes
body#2body.profileIdstring | null__1YesDestination profile ID. Pass null to remove the integration from its current profile.
body#2body.profileId[variant1]string__1_type:stringDestination profile ID. Pass null to remove the integration from its current profile.
body#2body.profileId[variant2]null__1_type:nullDestination profile ID. Pass null to remove the integration from its current profile.
response#3responseobject__0
response#3response.errorstring__1Yes