API Reference/Users/Handle a received invitation

Handle a received invitation

POSThttps://api.postpress.ai/v1/users/invite/received/{invitation_id}

Accept or decline a connection invitation that was received by the connected account.

Authorization

X-API-KEYstringrequired
API key from your postpress dashboard. Sent as a request header.

Path parameters

invitation_idstringrequired
The invitation id, as returned by List all invitations received.

Request body

Send exactly one of the variants below depending on the provider.

LinkedIn variantobject
LinkedIn variant object
providerstringLINKEDINrequired
shared_secretstringlength ≥ 1required
Token provided by LinkedIn. It is returned with each item from List all invitations received and is mandatory to handle the invitation.
account_idstringlength ≥ 1required
A unique identifier.
actionstringrequired
acceptdecline
Instagram variantobject
Instagram variant object
providerstringINSTAGRAMrequired
account_idstringlength ≥ 1required
A unique identifier.
actionstringrequired
acceptdecline

Response 200 OK

objectstringUserInvitationHandledrequired
statusstringrequired
ACCEPTEDDECLINED

Example request

curl --request POST \
  --url 'https://api.postpress.ai/api/v1/users/invite/received/inv_01HXYZ4QK3WJ8FN3M6QH7TZ8GR' \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "provider": "LINKEDIN",
    "shared_secret": "AQH...",
    "account_id": "acc_linkedin_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
    "action": "accept"
  }'

Example response

{
  "object": "UserInvitationHandled",
  "status": "ACCEPTED"
}

Errors

Every error response follows the same envelope:

titlestringrequired
Short error title.
detailstringoptional
Human-readable explanation.
instancestringoptional
Request identifier for support.
typestringrequired
Error type identifier.
statusnumberrequired
HTTP status code.
401 Unauthorized13 types

Credentials are missing, expired, or otherwise invalid.

  • errors/missing_credentials - Some credentials are necessary to perform the request.
  • errors/multiple_sessions - LinkedIn limits multiple sessions on certain Recruiter accounts. Use the cookie connection method.
  • errors/invalid_checkpoint_solution - The checkpoint resolution did not pass successfully. Retry.
  • errors/invalid_proxy_credentials - The provided proxy credentials are invalid.
  • errors/checkpoint_error - The checkpoint does not appear to be resolvable.
  • errors/invalid_credentials - The provided credentials are invalid.
  • errors/expired_credentials - Credentials have expired. Reconnect the account.
  • errors/insufficient_privileges - This resource is out of your API-key scopes.
  • errors/disconnected_account - The account is disconnected from the provider service.
  • errors/disconnected_feature - The service you're trying to reach is disconnected.
  • errors/invalid_credentials_but_valid_account_imap - IMAP/SMTP credentials are invalid but the account is otherwise valid.
  • errors/expired_link - This link has expired. Generate a new one.
  • errors/wrong_account - The provided credentials do not match the correct account.
403 Forbidden9 types

Authenticated but the account is restricted or the action is not allowed.

  • errors/account_restricted - The account has been restricted by the provider.
  • errors/account_mismatch - This action cannot be done with your account.
  • errors/insufficient_permissions - Valid authentication but insufficient permissions to perform the request.
  • errors/session_mismatch - Token user id does not match client session id.
  • errors/feature_not_subscribed - The requested feature has not been subscribed or authenticated properly.
  • errors/subscription_required - A subscription is required to use this feature.
  • errors/unknown_authentication_context - An additional step seems necessary to complete login.
  • errors/action_required - An additional step is required.
  • errors/resource_access_restricted - You don't have access to this resource.
500 Internal Server Error3 types

Something went wrong on our side or with the upstream provider.

  • errors/unexpected_error - Something went wrong.
  • errors/provider_error - The provider is experiencing operational problems. Retry later.
  • errors/authentication_intent_error - The current authentication intent was killed after failure.
501 Not Implemented1 types

The requested feature is planned but not yet available.

  • errors/feature_not_implemented - This feature has not been implemented yet.
503 Service Unavailable5 types

postpress is temporarily unable to handle the request.

  • errors/no_client_session - No client session is currently running.
  • errors/no_channel - No channel to client session.
  • errors/no_handler - Handler missing for that request.
  • errors/network_down - Network is down on the server side. Retry shortly.
  • errors/service_unavailable - Service temporarily unavailable. Retry later.
504 Gateway Timeout1 types

The upstream provider did not respond in time.

  • errors/request_timeout - Request timed out. Retry, and contact support if it persists.
Updated May 2026