API Reference/Users/Send an invitation

Send an invitation

POSThttps://api.postpress.ai/v1/users/invite

Send an invitation to add someone to your contacts. Implement carefully and respect provider limits and restrictions.

Authorization

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

Request body

provider_idstringrequired
The id of the user to add (the provider's id). Instagram: you may use the `provider_id` or the `username`. The `provider_messaging_id` does not work on this route.
account_idstringrequired
The linked account that will send the invitation.
user_emailstring
LinkedIn only. The email address of the user when it is required.
messagestring
Optional message to include with the invitation. Maximum 300 characters.

Response 200 OK

objectstringUserInvitationSentrequired
invitation_idstringrequired
Id of the newly created invitation.
usagenumber
Percentage of provider usage based on the limit. Triggers only at landings (50, 75, 90, 95).

Example request

{
  "provider_id": "ACoAACr-1eYBl...",
  "account_id": "acc_linkedin_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
  "user_email": "jordan@example.com",
  "message": "Hi Jordan, I'd love to connect."
}

Example response

{
  "object": "UserInvitationSent",
  "invitation_id": "inv_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
  "usage": 75
}

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.
400 Bad Request8 types

The request is malformed or a parameter is out of range.

  • errors/invalid_parameters - One or more parameters are invalid.
  • errors/malformed_request - The request body could not be parsed.
  • errors/content_too_large - The provided content exceeds the maximum size.
  • errors/invalid_url - A URL in the request is not valid.
  • errors/too_many_characters - The `message` exceeds the 300-character limit.
  • errors/unescaped_characters - Some characters in the request are not properly escaped.
  • errors/missing_parameters - Required parameters are missing.
  • errors/limit_too_high - The requested limit exceeds the allowed maximum.
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.
404 Not Found2 types

The account or user could not be found.

  • errors/resource_not_found - The requested resource was not found.
  • errors/invalid_resource_identifier - The provided identifier is not valid.
422 Unprocessable Entity13 types

The request is well-formed but cannot be fulfilled as-is.

  • errors/invalid_account - The provided account is not designed for this feature.
  • errors/invalid_recipient - The recipient is not valid.
  • errors/blocked_recipient - The recipient has blocked this kind of request.
  • errors/user_unreachable - The target user cannot be reached on the provider.
  • errors/unprocessable_entity - The request cannot be processed in its current form.
  • errors/action_already_performed - This invitation has already been sent.
  • errors/not_allowed_inmail - InMail is not allowed for this recipient.
  • errors/insufficient_credits - Not enough credits to send the invitation.
  • errors/limit_exceeded - The provider limit for invitations has been reached.
  • errors/already_invited_recently - An invitation was already sent recently to this user.
  • errors/already_connected - You are already connected with this user.
  • errors/cannot_invite_attendee - This attendee cannot be invited.
  • errors/provider_unreachable - The provider is currently unreachable.
429 Too Many Requests1 types

The provider is rate-limiting this account. Slow down and retry.

  • errors/too_many_requests - The provider cannot accept any more requests at the moment.
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