API Reference/Accounts/Retrieve an account

Retrieve an account

GEThttps://api.postpress.ai/v1/accounts/{id}

Returns the full details of a single account linked to your postpress workspace. The shape of `connection_params` depends on the provider `type`.

Authorization

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

Path parameters

idstringrequired
The id of the account to retrieve.

Response 200 OK

The response is a single Account object. The variants below mirror every provider type. Expand a variant to drill into its full schema.

Accountobjectrequired
One of the provider variants below, picked by the `type` field.
Account array
MOBILEobject
MOBILE object
objectstringAccountrequired
typestringMOBILErequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
phone_numberstringrequired
sim_serial_numberstringrequired
callobjectrequired
call object
phone_numberstringrequired
sim_serial_numberstringrequired
last_fetched_atstring
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
MAILobject
MAIL object
objectstringAccountrequired
typestringMAILrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
imap_hoststringrequired
imap_portnumberrequired
imap_userstringrequired
imap_encryptionstring
tlssslstarttlsdefault
smtp_hoststringrequired
smtp_portnumberrequired
smtp_userstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
GOOGLE_OAUTHobject
GOOGLE_OAUTH object
objectstringAccountrequired
typestringGOOGLE_OAUTHrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
idstringrequired
usernamestringrequired
calendarobjectrequired
calendar object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
ICLOUDobject
ICLOUD object
objectstringAccountrequired
typestringICLOUDrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
imap_hoststringrequired
imap_portnumberrequired
imap_userstringrequired
imap_encryptionstring
tlssslstarttlsdefault
smtp_hoststringrequired
smtp_portnumberrequired
smtp_userstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
OUTLOOKobject
OUTLOOK object
objectstringAccountrequired
typestringOUTLOOKrequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
idstringrequired
usernamestringrequired
calendarobjectrequired
calendar object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
GOOGLE_CALENDARobject
GOOGLE_CALENDAR object
objectstringAccountrequired
typestringGOOGLE_CALENDARrequired
connection_paramsobjectrequired
connection_params object
calendarstringrequired
sync_tokenstring
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
WHATSAPPobject
WHATSAPP object
objectstringAccountrequired
typestringWHATSAPPrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
phone_numberstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
LINKEDINobject
LINKEDIN object
objectstringAccountrequired
typestringLINKEDINrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
publicIdentifierstring
usernamestringrequired
premiumIdstring | nullrequired
premiumContractIdstring | nullrequired
premiumFeaturesarray of strings
premiumFeatures array
(item)string
recruitersales_navigatorpremium
organizationsarray of objectsrequired
organizations array
namestringrequired
messaging_enabledbooleanrequired
organization_urnstringrequired
mailbox_urnstringrequired
proxyobject
proxy object
sourcestringUSERrequired
hoststringrequired
portnumberrequired
protocolstring
httphttpssocks5
usernamestring
passwordstring
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
SLACKobject
SLACK object
objectstringAccountrequired
typestringSLACKrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
urlstringrequired
userstringrequired
user_idstringrequired
teamstringrequired
team_idstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
TWITTERobject
TWITTER object
objectstringAccountrequired
typestringTWITTERrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
EXCHANGEobject
EXCHANGE object
objectstringAccountrequired
typestringEXCHANGErequired
connection_paramsobjectrequired
connection_params object
mailobjectrequired
mail object
imap_hoststringrequired
imap_portnumberrequired
imap_userstringrequired
imap_encryptionstring
tlssslstarttlsdefault
smtp_hoststringrequired
smtp_portnumberrequired
smtp_userstringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
TELEGRAMobject
TELEGRAM object
objectstringAccountrequired
typestringTELEGRAMrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
user_idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
INSTAGRAMobject
INSTAGRAM object
objectstringAccountrequired
typestringINSTAGRAMrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.
MESSENGERobject
MESSENGER object
objectstringAccountrequired
typestringMESSENGERrequired
connection_paramsobjectrequired
connection_params object
imobjectrequired
im object
idstringrequired
usernamestringrequired
idstringlength ≥ 1required
A unique identifier.
namestringrequired
created_atstringrequired
An ISO 8601 UTC datetime (YYYY-MM-DDTHH:MM:SS.sssZ).
Example: 2025-12-31T23:59:59.999Z
current_signaturestringlength ≥ 1optional
A unique identifier.
signaturesarray of objects
signatures array
titlestringrequired
contentstringrequired
groupsarray of stringsrequired
Each item is a UniqueId (length ≥ 1).
sourcesarray of objectsrequired
sources array
idstringrequired
statusAccountSourceServiceStatusrequired
status enum
OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.

AccountSourceServiceStatus

Possible values for sources[].status:

OKstringOK
The Service is running normally.
STOPPEDstringSTOPPED
The Service has been stopped.
ERRORstringERROR
The Service has encountered an unspecified error and has been stopped.
CREDENTIALSstringCREDENTIALS
Credentials needs to be refreshed for the Service to be able to run.
PERMISSIONSstringPERMISSIONS
Some permissions are missing on the host Device for the Service to be able to run.
CONNECTINGstringCONNECTING
The Service is connecting.

Example response

{
  "object": "Account",
  "type": "LINKEDIN",
  "id": "acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR",
  "name": "Anna - Sales",
  "created_at": "2026-04-12T09:14:21.000Z",
  "connection_params": {
    "im": {
      "id": "ACoAAB7n2J0BV5...",
      "publicIdentifier": "anna-doe",
      "username": "anna-doe",
      "premiumId": null,
      "premiumContractId": null,
      "premiumFeatures": ["sales_navigator"],
      "organizations": [
        {
          "name": "Acme Inc.",
          "messaging_enabled": true,
          "organization_urn": "urn:li:organization:12345",
          "mailbox_urn": "urn:li:fsd_messagingThread:abc"
        }
      ]
    }
  },
  "current_signature": "sig_default",
  "signatures": [
    { "title": "Default", "content": "Sent from postpress" }
  ],
  "groups": [],
  "sources": [
    { "id": "messaging", "status": "OK" }
  ]
}

Example request

curl --request GET \
  --url 'https://api.postpress.ai/api/v1/accounts/acc_01HXYZ4QK3WJ8FN3M6QH7TZ8GR' \
  --header 'X-API-KEY: pp_live_...' \
  --header 'accept: application/json'

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, e.g. `errors/resource_not_found`.
statusnumberrequired
HTTP status code.
400 Bad Request8 types

The request can't be processed because of malformed or invalid input.

  • errors/invalid_parameters - One or more request parameters are invalid or missing.
  • errors/missing_parameters - One or more request parameters are missing.
  • errors/malformed_request - The given request has been rejected by the provider.
  • errors/content_too_large - The request payload is too large for the provider.
  • errors/invalid_url - The provided URL is not valid.
  • errors/too_many_characters - The provided content exceeds the character limit.
  • errors/unescaped_characters - The request path contains unescaped characters.
  • errors/limit_too_high - Pagination limit too high. See API reference for details.
401 Unauthorized13 types

Credentials are missing, expired, or 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 to avoid this.
  • 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. Contact support if it persists.
  • 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.
404 Not Found2 types

The requested account does not exist or is not accessible with this API key.

  • errors/resource_not_found - The requested resource was not found.
  • errors/invalid_resource_identifier - The provided resource identifier is invalid.
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. Start again from the beginning.
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