API Documentation

List Identities:

Retrieves a list of all synthetic identities associated with the authenticated account. Each object in the returned array represents one identity and contains summarized information. Use each one's id to make other API calls related to this identity.

Request

This endpoint does not require any request body or query parameters.

Response Body

Returns No identities were found If no identities are found for the account, it may return an error if you have not bad credentials or improperly configured your account.

• id (string): A unique identifier for the synthetic identity. Use this ID for other API calls related to this specific identity.
• picture (string): A base64 encoded string representing the identity's profile picture, resized to a low (256x256) dimension. you will need to add a data URI scheme like data:image/png;base64,... at the beginning to display the image.
• name (string): The full name associated with the synthetic identity.
• email (string): The email address associated with this identity including both the username and domain.
• phone (string): The phone number associated with this identity in the E164 standard format
• card (integer): The virtual payment card number associated with this identity,
• country (string): The ISO 3166 country code derived from the identity's location.
• location (string): The formatted location string associated with the identity, the city first then the country.
• accounts (integer): The number of associated online accounts stored for this identity.

Retrieve Information:

Retrieves detailed information for a specific synthetic identity identified by its unique ID. This endpoint provides a comprehensive view of the identity's attributes stored within ShadowSelf.

Request

This endpoint requires the identity's unique id as a path parameter. It does not require any request body or query parameters.

Response Body

Returns a JSON object containing the detailed attributes of the requested identity. If the ID is not found or does not belong to the authenticated user, an appropriate error (e.g., 404 Not Found, 403 Forbidden) will be returned.

• id (string): The unique identifier for the synthetic identity.
• creation_date (string): The timestamp (ISO 8601 format) indicating when the identity was created.
• proxy_server (string): The proxy server address associated with this identity.
• user_agent (string): The browser user agent string associated with this identity.
• picture (string): A base64 encoded string representing the identity's profile picture. Prepend data:image/png;base64, to display.
• name (string): The full name associated with the synthetic identity.
• bio (string): A short biography or description associated with the identity.
• age (integer): The age associated with the identity.
• sex (string): The assigned sex ('male' or 'female') for the identity.
• ethnicity (string): The assigned ethnicity for the identity.
• location (string): The formatted location string (e.g., "City, Country").
• email (string): The primary email associated with this identity.
• phone (string): The virtual phone number associated with this identity (E.164 format).
• card (string): The virtual payment card number associated with this identity.

Regenerate Name:

Regenerates the full name for a specific synthetic identity. This uses a localization-aware generator based on the identity's country. You can optionally specify the desired sex to influence the generated name.

Request

This endpoint requires the identity's unique id as a path parameter and accepts an optional JSON request body.

• sex (string, optional): Specify 'male' or 'female' to guide name generation. If omitted, the identity's current sex setting is used.

Response Body

Returns a JSON object containing the newly generated name.

• name (string): The newly generated full name for the identity.

Regenerate Bio:

Regenerates the biography (bio) for a specific synthetic identity. This uses a localization-aware generator based on the identity's country to create a plausible short bio.

Request

This endpoint requires the identity's unique id as a path parameter. It does not accept any request body or query parameters.

Response Body

Returns a JSON object containing the newly generated biography.

• bio (string): The newly generated biography for the identity.

Regenerate Picture:

Regenerates the profile picture for a specific synthetic identity. This uses Stable Diffusion Core to generate a new picture influenced by the identity's characteristics. You can optionally provide specific characteristics in the request body to guide the generation process.

Request

This endpoint requires the identity's unique id as a path parameter and accepts an optional JSON request body containing parameters to influence image generation.

• sex (string, optional): Must be 'male' or 'female'.
• age (integer, optional): Must be a whole number between 18 and 60.
• ethnicity (string, optional): Must be a valid ethnicity string from the allowed list (check dashboard for the list).
• bio (string, optional): A string used as a prompt hint. Must be between 10 and 126 characters if provided.

Response Body

Returns a JSON object containing the newly generated profile picture as a base64 encoded string.

• picture (string): The new base64 encoded profile picture data. Prepend data:image/png;base64, to display.

Update Information:

Updates one or more attributes of a specific synthetic identity. This endpoint allows modifying core characteristics like name, bio, age, sex, ethnicity, and profile picture.

Request

This endpoint requires the identity's unique id as a path parameter and a JSON request body containing the fields to update.

• name (string, optional): Must be 2-30 characters long. Allows letters, spaces, hyphens, apostrophes.
• bio (string, optional): Must be 10-126 characters long if provided (can be empty string "" to clear).
• sex (string, optional): Must be 'male' or 'female'.
• age (integer, optional): Must be a whole number between 18 and 60.
• ethnicity (string, optional): Must be a valid ethnicity string from the allowed list.
• picture (string, optional): Must be a valid base64 encoded string (without data URI prefix). Use with caution, typically regenerated rather than manually set.

Response Body

Returns a JSON object containing the current values of all the updatable fields (name, bio, sex, age, ethnicity, picture) after the update operation has been applied.

• name (string): The current name.
• bio (string): The current biography.
• sex (string): The current sex.
• age (integer): The current age.
• ethnicity (string): The current ethnicity.
• picture (string): The current base64 encoded picture data.

Retrieve Recent Emails:

Fetches a list of the most recent emails (up to 7 per mailbox) from the primary mailboxes (INBOX, Sent, Drafts, Junk) associated with the specified identity's email account. It also returns the total message count for each of these mailboxes. This provides an initial snapshot of recent activity and mailbox sizes.

Request

Requires the identity :id as a path parameter. No request body or query parameters are needed.

Response Body

Returns a JSON payload containing message counts and separate arrays of recent email objects for each primary mailbox.

• messagesCount (integer): Total number of emails in the INBOX.
• sentMessagesCount (integer): Total number of emails in the 'Sent' mailbox.
• draftsMessagesCount (integer): Total number of emails in the 'Drafts' mailbox.
• junkMessagesCount (integer): Total number of emails in the 'Junk' mailbox.
• inbox (array): An array containing the most recent email objects from the INBOX.
• sent (array): An array containing the most recent email objects from the 'Sent' mailbox.
• drafts (array): An array containing the most recent email objects from the 'Drafts' mailbox.
• junk (array): An array containing the most recent email objects from the 'Junk' mailbox.

Each email object within the arrays (`inbox`, `sent`, `drafts`, `junk`) includes:

• uid (integer): Unique ID of the email within its mailbox.
• messageID (string): The globally unique Message-ID header value. Can be empty for drafts.
• from (string): Sender's email address.
• to (string): Primary recipient's email address.
• subject (string): Email subject line.
• date (string): Date and time (ISO 8601 format).
• body (string): A snippet or the full body of the email.
• type (string): Format of the body ('html' or 'text').
• inReplyTo (string): The Message-ID this email is replying to.
• references (array): An array of Message-IDs (string) for threading.
• attachments (array): An array of attachment objects. Each object contains:
  • filename (string): Name of the attachment file.
  • data (string): Base64 encoded attachment data.

Retrieve More Emails:

Fetches the next batch of emails (up to 7) from a specific mailbox, used for pagination. Requires specifying the mailbox and the UID (`since`) of the oldest email currently loaded for that mailbox. The API returns emails with UIDs lower than the provided `since` value.

Request

Requires the identity :id as a path parameter and query parameters to specify the mailbox and pagination reference point.

• mailbox (Query Parameter, string): The name of the mailbox to fetch from (e.g., "INBOX", "Sent", "Drafts", "Junk").
• since (Query Parameter, integer): The UID of the oldest email currently fetched/displayed for this mailbox. The API will fetch the next batch of emails older than (i.e., with UIDs less than) this value.

Response Body

Returns a JSON payload containing the mailbox queried, the 'since' UID used, and an array of the next batch of emails found (up to 7).

• mailbox (string): The mailbox that was queried.
• since (integer): The UID used as the reference point for fetching.
• nextEmails (array): An array containing the next batch of email objects fetched. The structure of each email object is the same as described in "Retrieve Recent Emails". Returns an empty array if no older emails are found.

Retrieve Reply:

Fetches the full content of a specific email, identified by its unique message ID (`uuid` parameter, corresponding to the email's `messageID` header). This retrieves details needed for replying/forwarding like headers, subject, recipients, and attachments.

Request

Requires the identity :id as a path parameter and the email's `uuid` (Message-ID) as a query parameter.

• uuid (Query Parameter, string): The unique Message-ID of the email to fetch.

Response Body

Returns a JSON payload containing the `uuid` queried and the full details of the fetched email.

• uuid (string): The message ID requested.
• fetchEmail (object): An object containing the full email details, or null if not found. Includes:
  • uid (integer)
  • messageID (string)
  • from (string)
  • to (string)
  • subject (string)
  • date (string)
  • body (string)
  • type (string)
  • inReplyTo (string)
  • references (array of string)
  • attachments (array): Array of objects with filename (string) and data (string - base64).

Send Email:

Sends a new email or a reply/forward from the identity's email account. Allows setting recipient, subject, body, attachments, and threading headers. Can optionally delete a draft if the sent email originates from one.

Request

Requires the identity :id as a path parameter and a JSON payload with email details.

• Request Body (JSON):
  • to (string): Primary recipient's email address.
  • subject (string): Subject line (max 126 chars).
  • body (string): Body content (min 2 chars).
  • inReplyTo (string, optional): Message-ID being replied to.
  • references (array, optional): Array of Message-IDs (string) for threading.
  • attachments (array, optional): Array of attachment objects (max 10). Each object:
    • filename (string): Filename.
    • data (string): Base64 content (max ~15MB).
  • draft (integer, optional): UID of an existing draft to delete after sending.

Response Body

Returns a JSON payload confirming draft deletion and details of the sent email saved to 'Sent'.

• draft (integer): UID of deleted draft, or null.
• sentEmail (object): Details of the sent email:
  • uid (integer): UID in 'Sent'.
  • messageID (string): New Message-ID assigned.
  • from (string): Sender's address.
  • to (string): Primary recipient.
  • subject (string): Subject line.
  • date (string): Date sent.
  • body (string): Body content.
  • type (string): Body type (html or text)
  • attachments (array): Sent attachments.
  • inReplyTo (string): Message-ID being replied to.
  • references (array): Array of Message-IDs for threading.

Forward Email:

Forwards an existing email (identified by UID) to a new recipient. Subject is prefixed "FWD: " and body prepended with headers. Original attachments are included.

Request

Requires identity :id path parameter and JSON payload with UID and forward address.

• Request Body (JSON):
  • uid (integer): UID of the email to forward (positive integer).
  • forward (string): Recipient email address for forwarding.

Response Body

Returns JSON payload with original UID, forward address, and details of the new forwarded email saved in 'Sent'.

• uid (integer): UID of the original forwarded email.
• forward (string): Address email was forwarded to.
• forwardEmail (object): Details of the new forwarded email (similar structure to `sentEmail`, includes attachments with data).

Save Draft:

Saves an email composition as a draft in 'Drafts'. Can replace an existing draft if its UID is provided (optional draft field). Saves recipients, subject, body, attachments, and threading headers.

Request

Requires identity :id path parameter and JSON payload with draft details. Uses PUT.

• Request Body (JSON): Structure matches "Send Email" body.
  • draft (integer, optional): UID of existing draft to replace. Omit to create new.
  • to (string): Draft recipient.
  • subject (string): Draft subject.
  • body (string): Draft body.
  • inReplyTo (string, optional): Draft In-Reply-To header (Message-ID format).
  • references (array, optional): Draft References header (array of Message-IDs).
  • attachments (array, optional): Draft attachments (array of objects with filename and data).

Response Body

Returns JSON payload confirming old draft replacement and details of the saved draft in 'Drafts'.

• draft (integer): UID of replaced draft, or null.
• savedDraft (object): Details of the saved draft (includes `uid`, `messageID` (null), `mailbox` ("Drafts"), `from`, `to`, `subject`, `body`, `type`, `date`, `attachments`, `inReplyTo`, `references`).

Delete Email:

Moves a specific email (identified by mailbox and UID) to the 'Junk' folder. Emails moved to 'Junk' are automatically and permanently deleted after 7 days. This action cannot be performed on emails already residing in the 'Junk' folder.

Request

Requires identity :id path parameter and JSON payload specifying mailbox and UID to move to Junk.

• Request Body (JSON):
  • mailbox (string): Mailbox where the email currently resides (e.g., "INBOX", "Sent", "Drafts"). Cannot be "Junk".
  • uid (integer): UID of the email within the specified mailbox (positive integer).

Response Body

Returns JSON payload confirming mailbox and UID targeted for moving to Junk. Check HTTP status code (e.g., 200 OK) for success.

• mailbox (string): Mailbox specified in request.
• uid (integer): UID specified in request.

Retrieve Messages:

Retrieves a list of conversations associated with the identity's phone number. For each conversation (grouped by the other party's phone number), all messages are returned. The list is sorted with the most recent conversation first.

Request

Requires the identity :id as a path parameter. No request body or query parameters are needed.

Response Body

Returns a JSON payload containing an array of message objects, where each object represents the latest message in a distinct conversation thread.

• messages (array): An array of the latest message objects from each conversation, sorted reverse-chronologically by message date. Each message object includes:
  • messageID (string): The unique identifier for the message.
  • status (string): Delivery status of the message (e.g., 'sent', 'delivered', 'failed', 'received').
  • date (string): Date and time the message was sent or created (ISO 8601 format).
  • error (string): Contains error code and message if the message failed (e.g., "30008: Unknown error"), otherwise an empty string.
  • body (string): The content of the SMS message.
  • from (string): Sender's phone number (E.164 format).
  • to (string): Recipient's phone number (E.164 format).

Retrieve Conversation:

Fetches the complete message history for a specific conversation between the identity's phone number and another phone number (`addressee`). The messages are sorted reverse-chronologically (most recent first).

Request

Requires the identity :id as a path parameter and the other party's phone number (`addressee`) as a query parameter.

• addressee (Query Parameter, string): The E.164 formatted phone number of the other party in the conversation (e.g., `+14155550000`). Cannot be the identity's own phone number.

Response Body

Returns a JSON payload containing the addressee number and an array of all message objects in the conversation.

• addressee (string): The phone number of the other party in the conversation.
• conversation (array): An array containing all message objects exchanged between the identity and the addressee, sorted reverse-chronologically. The structure of each message object is the same as described in "Retrieve Messages", this means:
• messageID (string): The unique identifier for the message.
• status (string): Delivery status of the message (e.g., 'sent', 'delivered', 'failed', 'received').
• date (string): Date and time the message was sent or created (ISO 8601 format).
• error (string): Contains error code and message if the message failed (e.g., "30008: Unknown error"), otherwise an empty string.
• body (string): The content of the SMS message.
• from (string): Sender's phone number (E.164 format).
• to (string): Recipient's phone number (E.164 format).

Send Message:

Sends an SMS message from the identity's phone number to a specified recipient (`addressee`).

Request

Requires the identity :id as a path parameter and a JSON payload containing the recipient and message body.

• Request Body (JSON):
  • addressee (string): The recipient's phone number in E.164 format (e.g., `+14155550000`). Cannot be the identity's own number.
  • body (string): The text content of the SMS message. Must be between 2 and 160 characters.

Response Body

Returns a JSON payload containing the recipient addressee and details of the message successfully sent.

• addressee (string): The recipient phone number specified in the request.
• messageSent (object): An object containing details of the sent message including:
• messageID (string): The unique identifier for the message.
• status (string): Delivery status of the message (e.g., 'sent', 'delivered', 'failed', 'received').
• date (string): Date and time the message was sent or created (ISO 8601 format).
• error (string): Contains error code and message if the message failed (e.g., "30008: Unknown error"), otherwise an empty string.
• body (string): The content of the SMS message.
• from (string): Sender's phone number (E.164 format).
• to (string): Recipient's phone number (E.164 format).

Delete Conversation:

Permanently deletes all SMS messages exchanged between the identity's phone number and the specified `addressee` number. This action is irreversible.

Request

Requires identity :id path parameter and JSON payload specifying the addressee whose conversation should be deleted.

• Request Body (JSON):
  • addressee (string): The E.164 formatted phone number of the other party whose conversation history should be deleted.

Response Body

Returns JSON payload confirming the addressee whose conversation was targeted for deletion. Check HTTP status code (e.g., 200 OK) for success confirmation.

• addressee (string): The phone number specified in the request.

Retrieve Accounts:

Retrieves all stored online account entries associated with the specified synthetic identity.

Request

Requires the identity :id as a path parameter. No request body or query parameters are needed.

Response Body

Returns a JSON payload containing an array of stored account objects. The password and totp fields will contain the client-side encrypted data as stored.

• accounts (array): An array of account objects associated with the identity. Each object includes:
  • id (integer): The unique identifier for this specific account entry.
  • username (string): The stored username for the online account.
  • password (string): The client-side encrypted password. Your client must decrypt this.
  • website (string): The URL of the website associated with the account.
  • totp (string): The client-side encrypted TOTP secret key. Your client must decrypt this to generate codes.
  • algorithm (string): The algorithm used for TOTP generation ('SHA1', 'SHA256', 'SHA512'), relevant only if totp is set.

Add Account:

Adds a new online account entry associated with the specified identity. Remember to encrypt the password and totp secret on the client-side before sending.

Request

Requires the identity :id as a path parameter and a JSON payload containing the account details.

• Request Body (JSON):
  • username (string): The username (max 25 chars).
  • password (string): The client-side encrypted password data (e.g., Base64).
  • website (string, optional): The website URL.
  • totp (string, optional): The client-side encrypted TOTP secret key data (e.g., Base64).
  • algorithm (string, optional): The TOTP algorithm ('SHA1', 'SHA256', 'SHA512'). Required if totp is provided.

Response Body

Returns a JSON payload confirming the details of the added account, including its new id. Sensitive fields are returned as sent (encrypted).

• id (integer): The unique ID assigned.
• username (string)
• password (string): The encrypted password provided.
• website (string)
• totp (string): The encrypted TOTP secret provided.
• algorithm (string)

Edit Account:

Updates an existing online account entry identified by its unique id. Provide the account entry's id in the request body. Encrypt password and totp client-side if updating them.

Request

Requires the identity :id (owner) path parameter and JSON payload with account entry ID and fields to update.

• Request Body (JSON):
  • id (integer): The unique ID of the account entry to edit.
  • username (string): Updated username (max 25 chars).
  • password (string): Updated client-side encrypted password data.
  • website (string, optional): Updated website URL.
  • totp (string, optional): Updated client-side encrypted TOTP secret data.
  • algorithm (string, optional): The TOTP algorithm ('SHA1', 'SHA256', 'SHA512'). Required if totp is updated.

Response Body

Returns JSON payload confirming the details of the updated account entry. Sensitive fields returned encrypted.

• id (integer): ID of edited entry.
• username (string)
• password (string): Updated encrypted password.
• website (string)
• totp (string): Updated encrypted TOTP secret.
• algorithm (string)

Update Encryption:

Updates the encrypted password and/or totp fields for multiple account entries at once. This is primarily for re-encrypting credentials client-side, e.g., after changing a master password.

Retrieve all accounts, re-encrypt sensitive fields (password, totp) client-side with the new key/method, then send an array containing objects for each account entry needing update, including its id and the newly encrypted password and/or totp.

Request

Requires identity :id path parameter and JSON payload with an array of accounts with newly re-encrypted data.

• Request Body (JSON):
  • accounts (array): Array of account objects to update. Each object:
    • id (integer): Unique ID of the account entry.
    • password (string): Newly client-side re-encrypted password data.
    • totp (string, optional): Newly client-side re-encrypted TOTP secret. Include only if the entry has a TOTP secret.

Response Body

Returns JSON payload confirming the update by echoing back the array of account objects sent. Check HTTP status code for success.

• accounts (array): Array of account update objects sent in the request.

Delete Account:

Permanently deletes a specific stored online account entry using its unique ID. This action is irreversible.

Request

Requires the identity :id (owner) path parameter and JSON payload specifying the unique ID of the account entry to delete.

• Request Body (JSON):
  • id (integer): The unique ID of the account entry to delete (positive integer).

Response Body

Returns JSON payload confirming the ID of the account entry targeted for deletion. Check HTTP status code (e.g., 200 OK) for success.

• id (integer): The ID specified in the request.