Ortto

1. Overview

Ortto is a unified customer journey platform designed for marketing automation, analytics, and customer data management.

Through the GoInsight Ortto node, you can seamlessly integrate customer data and marketing automation into your workflows. You can manage your contacts, accounts, audiences, and activities, including:

• Finding, retrieving, creating, updating, and deleting people and account records.
• Managing account associations by adding or removing people from accounts.
• Searching audiences and subscribing contacts to specific marketing lists.
• Defining custom activities and tracking user events to trigger automations.

2. Prerequisites

• Account Requirement: Before using this node, you need to have a valid Ortto account.
• Permission Requirement: You may need administrator or specific API access permissions to generate API keys and manage data within your Ortto workspace.

3. Credentials

For detailed instructions on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on the following resources: Account, People, Audience, and Activity.

Operation Details

Find Account

Find account records in Ortto. Use this to search and list accounts with pagination and filtering; for retrieving a specific account by ID, use 'Get Account' (if available) or this action with AccountId.

Options:

• SearchQuery: General text search across account name and fields. Example: "Acme"
• AccountId: The unique identifier for the account. Obtain from the 'Find Account' action results (using SearchQuery) or the Ortto UI account details page URL. Example: "10626f6df9a865ba45d95300"
• Limit: Number of records to return per page (1-500). Default: 50. Recommended: Use 100-200 for optimal performance. Higher values may impact response time. Example: 100
• Offset: Number of records to skip for page-based pagination. Use with 'Limit'. Formula: Offset = (page_number - 1) * Limit. Default: 0. Note: If 'CursorId' is provided, this parameter is ignored.
• CursorId: A pagination token (bookmark) for cursor-based pagination. Use the 'NextOffset' or 'CursorId' returned from a previous request to fetch the next page. When used, the 'Offset' parameter is ignored. Example: "00609c898a4490c5800a5453"
• AdditionalFields: Advanced search and display options. Supported Parameters: filter_conditions, fields, sort_by_field_id, sort_order, account_type, inclusion_ids, exclusion_ids. Example: {"filter_conditions": [{"field_id": "str:o:name", "operator": "$eq", "value": "Acme"}], "fields": "str:o:name, geo:o:country"}

Output:

• Accounts (object-array): List of found accounts. Each account includes a 'fields' object containing requested properties. Common fields: str:o:id (Account ID), str:o:name (Name), str:o:industry (Industry), int:o:employees (Employees), str:o:website (Website), geo:o:country (Country).
• Meta (object): Pagination and summary metadata. Includes: TotalContacts (number), TotalAccounts (number), TotalMatches (number), TotalSubscribers (number), Offset (number), HasMore (boolean).
• Offset (number): Current query offset for pagination.
• NextOffset (number): Offset for retrieving the next page of accounts.
• CursorId (string): Cursor ID for retrieving the next page of accounts.
• HasMore (bool): Whether there are more account pages available.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Get Account

Retrieve detailed account information from Ortto using account IDs. Use this to get specific accounts; for searching accounts based on criteria use 'Search Accounts'.

Input Parameters:

• AccountIds: Comma-separated list of Account IDs to retrieve. Each ID must be a 24-character hexadecimal string. Format: 24-char hex (e.g., 10668b9d5c7d7d6dd895e100). How to get: Use 'Search Accounts' action to find IDs, copy from Ortto account detail page URL, or export from Ortto reports. Example: 10668b9d5c7d7d6dd895e100,1066276f1272c7d821defc00

Options:

• Fields: Comma-separated string of fields to return using Ortto syntax: {type}:o:{field_name}. Supported types: str (string), int (integer), dtz (datetime). Common Fields: str:o:name (Account name), str:o:industry (Industry), int:o:employees (Employee count), str:o:id (Account ID). Default: str:o:name, str:o:industry, int:o:employees, str:o:id.

Output:

• TotalCount (number): Total number of account IDs queried.
• RetrievedCount (number): Number of accounts successfully retrieved.
• FailedCount (number): Number of accounts that failed to retrieve.
• Accounts (object-array): List of retrieved account objects. Object Structure: id (string, 24-char hex ID), name (string, Account name), industry (string, Industry category), employees (integer, Number of employees). Other fields depend on the 'Fields' input parameter.
• Meta (object): Execution metadata. Object Structure: total_requested (integer, Count of IDs in request), total_found (integer, Count of accounts successfully matched).
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Upsert Accounts

Upsert (create or update) account records in Ortto. Use this to batch process account data; updates existing records if matches are found based on 'MergeBy' criteria, otherwise creates new ones.

Input Parameters:

• AccountsData: The list of account records to create or update. Each record is an object where keys are Ortto Field IDs. These IDs require a technical prefix to define the data type: 'str:o:' (String/Text, e.g., str:o:name), 'int:o:' (Integer/Number, e.g., int:o:employee_count), 'bol:o:' (Boolean/True-False, e.g., bol:o:is_active), 'dtz:o:' (DateTime in ISO8601, e.g., dtz:o:created_at), 'geo:o:' (Geographic location). Using prefixes ensures data is stored in the correct format. Tip: Use 'Get Account Fields' action to retrieve field names with correct prefixes.
• MergeBy: Defines the 'search keys' used to find existing accounts to update. Think of it as: 'Which company information should we use to check if this account already exists?'. Format: Use Ortto field names with type prefixes. Common fields: 'str:o:name' (Company Name), 'str:o:website' (Website URL), 'str:o:email' (Company Email), 'str:o:phone' (Phone Number), 'str:o:external_id' (External System ID). Max 2 fields allowed. Note: If 'account_id' is provided in AccountsData, it overrides this setting. Tip: Use 'Get Account Fields' action to retrieve the complete list.

Options:

• AsyncProcessing: Whether to use asynchronous processing. Default is false. True: async processing with immediate confirmation response. False: sync processing waiting for completion.
• MergeStrategy: Strategy for merging data into existing records. 1: Append only (Only fill empty fields, don't overwrite existing values. Use for enriching records without losing data). 2: Overwrite (Recommended. Replace existing values with new data. Use for syncing latest data from CRM). 3: Ignore (Skip updating if record already exists. Use for initial one-time migrations).
• FindStrategy: Matching logic when multiple MergeBy fields are provided. 0: Match any (Recommended. Finds record if ANY provided field matches. Use when companies have multiple identifiers like Name OR Website). 1: Strict priority (Only checks the next field if the previous one is empty in the database. Use for hierarchical matching, e.g., try External ID first, fallback to Name).

Output:

• ProcessedCount (number): Number of accounts successfully processed for creation or update.
• FailedCount (number): Number of accounts that failed to process.
• TotalCount (number): Total number of accounts in the request.
• IsAsync (bool): Whether the processing was done asynchronously.
• Results (object-array): List of processing results for each input account. Fields per object: 'status' (string: 'created', 'updated', 'error', or 'suppressed'); 'account_id' (string: Ortto unique identifier); 'matched_by' (string, optional: The field name used to match an existing account. Only present when status is 'updated'); 'error' (string, optional: Detailed error message. Only present when status is 'error').
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200, 201, 202).
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors), 500 = system error, -1 = parameter validation error.
• ErrorMessage (string): Error description if operation fails, empty string on success.

Delete Account

⚠️ WARNING: This operation PERMANENTLY deletes account records and CANNOT BE UNDONE. Deleted accounts cannot be recovered. \n\nPre-conditions: Accounts MUST be archived before they can be deleted. Attempting to delete an active account will result in a 403 Forbidden error. \n\nData Impact: Deleting an account will also remove all associated contacts, activities, and custom data linked to this account. This operation does NOT trigger Ortto's internal automation rules or webhooks.

Options:

• InclusionIds: Comma-separated string of account IDs to delete. \n\nHow to get IDs: Use the 'Get Account' or 'Search Accounts' action to retrieve valid account IDs, or copy the ID from the account profile URL in Ortto. \n\nFormat: Multiple IDs should be separated by commas (e.g., 'id1, id2'). Spaces after commas are handled automatically. \n\nNote: This parameter is REQUIRED if AllRowsSelected is false, and IGNORED if AllRowsSelected is true. Example: "00609384fa6de6e7a8d89d01, 00626f6dfba865ba45d9c200"
• AllRowsSelected: Bulk Delete Mode: Set to true to delete ALL currently archived accounts. \n- True: Deletes all archived records. InclusionIds will be ignored. \n- False (Default): Only deletes accounts specified in InclusionIds.
• ExclusionIds: Comma-separated string of account IDs to exclude from bulk deletion. \n\nIMPORTANT: This parameter ONLY works when AllRowsSelected is set to true. It is ignored in specific deletion mode (AllRowsSelected=false). Example: "1064349bbcb6452533ae1100"

Output:

• ScheduledAccounts (number): Number of accounts scheduled for deletion (to be deleted).
• DeletedAccounts (number): Number of accounts already deleted.
• TotalRequested (number): Total number of accounts requested for deletion. \n- Specific mode: Count of InclusionIds. \n- Bulk mode (AllRowsSelected=true): Returns -1 while the operation is being initialized, updated to actual count in final response.
• RequestType (string): Request type: 'bulk' or 'specific'.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 403 for forbidden).
• StatusCode (number): HTTP status code indicating operation result: \n- 200: Deletion completed successfully (synchronous). \n- 202: Deletion request accepted and scheduled (asynchronous, check ScheduledAccounts for pending count). \n- 403: Forbidden (Account not archived or insufficient permissions).
• ErrorMessage (string): Error description if operation fails, empty string on success.

Add People to Account

Associate people with an account in Ortto. Use this to link contacts to an organization. This operation is irreversible.

Input Parameters:

• AccountId: The 24-character hex string ID of the account. Get this from 'Search Accounts' action or the dashboard URL. Example: "507f1f77bcf86cd799439011"

Options:

• PersonIds: ⚠️ Mutually exclusive with FilterData - provide ONLY PersonIds OR FilterData, never both. A list of 24-character hex string IDs of people to add, separated by commas. Example: "00609384fa6de6e7a8d89d01, 006046baa37f2e24cc56f122"
• FilterData: ⚠️ Mutually exclusive with PersonIds - provide ONLY FilterData OR PersonIds, never both. Filter conditions object to select people. \n\nExample Structure:\n{\n "$str::contains": {\n "field_id": "str::email",\n "value": "@acme.com"\n }\n}\n\nMultiple Conditions (AND):\n{\n "$and": [\n {\n "$str::contains": {\n "field_id": "str::email",\n "value": "@acme.com"\n }\n },\n {\n "$str::equals": {\n "field_id": "str::first-name",\n "value": "John"\n }\n }\n ]\n}
• OverwriteMode: If set to true, existing account associations for these people will be overwritten (people will be moved from their current account to the target account). If false, people already associated with other accounts will be silently skipped (no error will be raised, but ProcessedCount will be lower than the input count). Default is true.

Output:

• Success (bool): Whether the operation was executed successfully.
• AccountId (string): The target account ID where people were added.
• ProcessedCount (number): The total number of contacts successfully associated with the account. Returns 0 if no matches were found via FilterData or if all provided PersonIds were invalid/already associated.
• Message (string): Operation result description message. Typical formats:\n- Success: 'Successfully added {count} people to account {account_id}'\n- Partial success: 'Added {count} people, {skipped} skipped (already associated)'\n- Failure: 'Failed to add people: {error_reason}'
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200, 400, 401).
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors), 500 = system error, -1 = parameter validation error.
• ErrorMessage (string): Error description if operation fails, empty string on success.

Remove People from Account

⚠️ WARNING: This operation permanently removes contacts from the account and cannot be undone. Removed contacts cannot be recovered.

Remove contacts from an Ortto account. Use this to delete contacts by ID list or filter criteria.

Input Parameters:

• AccountId: The unique identifier of the account. \n\nHow to get Account ID:\n- Call Get Account or Search Accounts actions to retrieve the ID.\n- Or copy from the account details page URL in Ortto.\n\nExample: "acc_5f8a9b2c3d4e1234567890ab"

Options:

• InclusionIds: ⚠️ IMPORTANT: Cannot be used together with FilterData. Either InclusionIds or FilterData must be provided. \n\nList of contact IDs to remove from the account. Each ID is a 24-character hexadecimal string. \n\nHow to get contact IDs:\n- Call Get People or Search People actions to retrieve IDs.\n- Or copy from the contact details page URL in Ortto (e.g., the string after '/people/').\n\nExample: ["00609384fa6de6e7a8d89d01", "006046baa37f2e24cc56f122"]
• FilterData: Filter criteria to identify contacts for removal. At least one of InclusionIds or FilterData must be provided. Cannot be used together with InclusionIds. \n\nExample Structure:\n\nSingle condition:\n{\n "$str::contains": {\n "field_id": "str::email",\n "value": "@example.com"\n }\n}\n\nMultiple conditions (AND):\n{\n "$and": [\n {\n "$str::contains": {\n "field_id": "str::email",\n "value": "@example.com"\n }\n },\n {\n "$str::equals": {\n "field_id": "str::first",\n "value": "John"\n }\n }\n ]\n}

Output:

• IsSuccess (bool): Whether the operation completed successfully.
• AccountId (string): The target account ID from which contacts were removed.
• PeopleRemoved (string-array): List of contact IDs that were successfully removed. Each ID is a 24-character hexadecimal string. Returns an empty array if no contacts matched the criteria.
• Message (string): Descriptive message about the operation result.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Find People

Search and retrieve people records from Ortto with pagination support. Use this to list multiple contacts with filters, search by name or email, or export contact lists; for getting a single person by ID use 'Get a Person'.

Options:

• Limit: Maximum number of records to return per page (max 100). Default is 50.
• Offset: The number of records to skip. Used for basic pagination.
• CursorId: A unique identifier for high-performance pagination (faster than Offset for large datasets). To fetch the next page, provide the 'CursorId' value returned from the previous response. Leave empty for the first request. This is a base64 encoded string. Example: "abc123def456"
• Fields: Comma-separated list of field IDs to include in the response. Field ID Format: IDs use 'type::name' pattern. Common prefixes: 'str::' = Text fields (e.g., str::email), 'dtz::' = DateTime fields (e.g., dtz::created_at), 'int::' = Integer fields (e.g., int::age), 'phn::' = Phone fields (e.g., phn::mobile). Use 'Get Custom Fields' action to find available IDs. Example: "str::email, str::first, str::last"
• Q: Simple search query to filter people by name or email. Example: "john@example.com"
• TypeFilter: Filter by record status. Default behavior (empty string): returns only active records. Use 'archived' to include records that have been soft-deleted or moved to archive. Example: ""
• AdvancedOptions: Advanced search and sorting options. Most users can leave this empty. Fields: 'sort_by_field_id' (string): Field ID for sorting; 'sort_order' (string): 'asc' or 'desc'; 'filter' (object): Complex logic using AND/OR operators. Example: {"sort_by_field_id": "str::last", "sort_order": "asc", "filter": {"and": [{"field_id": "str::email", "filter": "contains", "value": "@gmail.com"}]}}

Output:

• Contacts (object-array): Array of contact objects. Each object contains: 'id' (string): Unique person UUID; 'fields' (object): Key-value pairs where keys are field IDs. Common fields include: 'str::email' (Email), 'str::first' (First name), 'str::last' (Last name), 'str::id' (External ID). Other custom fields as requested in the Fields parameter. Example: [{"id": "uuid-123", "fields": {"str::email": "test@test.com", "str::first": "John"}}]
• Meta (object): Pagination and summary metadata. Includes: TotalContacts (number): Total contacts in system; TotalAccounts (number): Total accounts; TotalMatches (number): Contacts matching current query; TotalSubscribers (number): Total subscribed contacts. Example: {"TotalContacts": 100, "TotalMatches": 5, "TotalSubscribers": 80}
• Offset (number): Current record offset for pagination.
• NextOffset (number): The offset value to use in the next request to retrieve the next page of results.
• CursorId (string): A base64 encoded cursor string used for high-performance pagination in large datasets.
• HasMore (bool): Indicates if more records are available beyond the current page.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200, 401, 404, 500).
• StatusCode (number): System status code. 200 for successful API communication, 500 for network/server errors.
• ErrorMessage (string): Error description if operation fails, empty string on success.

Get People

Retrieve detailed contact information from Ortto using contact IDs. Use this to get full profiles for specific contacts; for searching by criteria use 'Search People'.

Input Parameters:

• ContactIds: List of unique contact identifiers to retrieve. \n\nID Format: Each ID must be a 24-character hexadecimal string (e.g., 0066cc4c16dfd264d0e99b00).\n\nHow to get IDs: \n1. Use 'Search People' action and extract the 'id' field.\n2. Use 'List People' action and extract the 'id' field.\n\nExample:\n["0066cc4c16dfd264d0e99b00", "00668d816ce2d34c550fe300"]

Options:

• Fields: Comma-separated list of fields to return. Fields use a 'Type Prefix::Field Name' format. \n\nAvailable Prefixes:\n- str:: (String): e.g., str::email, str::first\n- phn:: (Phone): e.g., phn::phone\n- int:: (Integer): e.g., int::age\n- dtz:: (DateTime): e.g., dtz::created_at\n- bol:: (Boolean): e.g., bol::is_subscribed\n- geo:: (Geographic): e.g., geo::country\n- txt:: (Long Text): e.g., txt::description\n\nExample: "str::email, phn::phone, bol::is_subscribed"

Output:

• ContactCount (number): Number of contacts successfully retrieved.
• TotalRequested (number): Total number of contact IDs requested.
• Contacts (object-array): List of successfully retrieved contact objects. \n\nObject Structure:\n- id (string): The unique identifier of the contact.\n- fields (object): A map of requested field IDs to their values.\n - Example: {"str::email": "user@example.com", "str::first": "John"}\n\nAccess Pattern: Use Contacts[i].fields["str::email"] to access specific field data.
• Meta (object): Response metadata. \n- total (number): The number of contacts successfully retrieved in this request (matches ContactCount).\n- offset (number): Always 0 for this action.\n- has_more (boolean): Always false for this action.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Upsert People

Upsert multiple people into Ortto (batch operation, max 100 records). Use this to create or update contact records in batch; for single contact use 'Upsert a Person'.

Input Parameters:

• PeopleData: A list of people to upsert (max 100). Each object uses Field IDs as keys. Common Field IDs: 'str::email' (Email), 'str::first-name' (First Name), 'str::last-name' (Last Name), 'phn::phone' (Phone), 'str::external-id' (External ID). To find all available Field IDs, use the 'Get Custom Fields' action or refer to Ortto's Contact Fields documentation. Example: [{'str::email': 'jane.doe@example.com', 'str::first-name': 'Jane'}]
• MergeBy: The field ID rules to use for matching existing people. A 'Field ID' is a unique identifier formatted as 'type_prefix::field_name' (e.g., 'str::email', 'phn::phone'). To find correct IDs, use 'Get Custom Fields' action. Example: ["str::email", "phn::phone"]

Options:

• MergeStrategy: Strategy for merging data into existing records: 0 (Overwrite) - replaces existing values; 1 (Append Only) - only fills empty fields; 2 (Ignore) - does not update existing records. Default: 0.
• FindStrategy: Strategy to find existing people based on MergeBy fields. Options: 0 (Any) - match any one of the prefixed IDs provided; 1 (All) - must match all prefixed IDs provided; 2 (Exact) - strict matching with validation. Default: 2.
• AsyncProcessing: If true, the request is queued and processed asynchronously. Recommended for large batches. Default: true.
• AdditionalFields: Extended configuration options. Supported fields: 'merge_by_alt_fields' (string-array) - secondary identification fields; 'skip_non_existing' (bool) - if true, only updates existing records; 'suppression_list_field_id' (string) - custom field ID for suppression. Example: {"skip_non_existing": false}

Output:

• Results (object-array): List of upsert results for each person. Each item contains: 'status' (created/updated/ignored/failed/queued), 'person_id' (unique ID, null if async), 'matched_by' (field used for matching), 'error' (error details if failed), and 'data' (object: raw response data containing 'id', 'fields', 'tags').
• ProcessedCount (number): Number of contacts successfully processed for creation or update.
• FailedCount (number): Number of contacts that failed to process.
• TotalCount (number): Total number of contacts in the request.
• IsAsync (bool): Whether the processing was done asynchronously.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Delete People

Delete one or more contact records in Ortto. Use this to permanently remove contacts. ⚠️ WARNING: This operation cannot be undone.

Options:

• InclusionIds: Comma-separated string of contact IDs to delete. How to get IDs: Call Get People or Search People action and extract the id field from the returned contact objects. Alternatively, find the ID in the Ortto web app URL when viewing a profile: https://app.ortto.com/contacts/{ID}. Format: Multiple IDs should be separated by commas (e.g., "id1, id2"). Spaces after commas are optional and will be automatically trimmed. Example: "00609384fa6de6e7a8d89d01, 00626f6dfba865ba45d9c200"
• ExclusionIds: Comma-separated string of contact IDs to exclude from deletion. Scenario: Primarily used when AllRowsSelected is true to delete all archived contacts except for the specific IDs listed here. Format: Multiple IDs separated by commas. Spaces are optional. Example: "006281d8ff95c3ed70b70800"
• AllRowsSelected: Whether to bulk delete all archived contacts (where 'rows' refers to contact records). Logic: If set to false (default), InclusionIds becomes required to specify which contacts to delete. If set to true, all contacts currently in the 'Archived' state will be deleted, unless excluded via ExclusionIds.

Output:

• ScheduledContacts (number): Number of contacts scheduled for deletion.
• DeletedContacts (number): Number of contacts already deleted.
• TotalRequested (number): Total number of contacts requested for deletion. Note: Returns -1 when AllRowsSelected is true, as the exact count of all archived contacts is processed asynchronously by the bulk engine.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors), 500 = system error, -1 = parameter validation error.
• ErrorMessage (string): Error description if operation fails, empty string on success.

Find Audiences

Find audiences in Ortto. Use this to search and list audiences with filters and pagination; for getting a specific audience by ID use 'Get an Audience'.

Options:

• SearchTerm: Search keyword for filtering audiences by name. Supports partial matching (case-insensitive). For example: 'VIP' will match 'VIP Customers', 'VIP Members', 'New VIP List'. Leave empty to retrieve all audiences. Example: "VIP customers"
• WithFilter: Whether to include audience filter conditions in the response. True: Include the 'Filter' object containing entry/exit conditions (complex nested structure). False: Return basic information only (recommended for most use cases). Note: Filter objects contain rule definitions and may be large.
• Limit: Number of audiences to return (1-40). Default is 40. Used for pagination.
• Offset: Pagination offset. Default is 0. Specifies how many audience records to skip for subsequent pages.
• Archived: Whether to include archived audiences. True: return archived audiences, False: exclude archived audiences.
• Retention: Whether to return only retention audiences. \n\nWhat are Retention Audiences?\nRetention audiences are special audience types used for:\n- GDPR/privacy compliance (e.g., 'Users who opted out')\n- Data lifecycle management (e.g., 'Inactive users to be deleted')\n- Legal hold requirements (e.g., 'Accounts under investigation')\n\nWhen to use:\n- True: Filter to show only retention/compliance audiences (rarely needed)\n- False: Show all regular marketing audiences (recommended for 99% of use cases)\n\nNote: Most users should leave this as False unless specifically managing compliance workflows.

Output:

• Audiences (object-array): A JSON array of audience objects. Each audience object contains:\n\nCore Fields:\n- id (string): Unique audience identifier, format: aud_xxxxx\n- name (string): Audience display name\n- instance_id (string): Ortto workspace instance identifier\n- members (number): Total member count in this audience\n- subscribers (number): Active subscriber count (subset of members)\n- created (string): Creation timestamp in ISO 8601 format (e.g., 2024-01-15T10:30:00Z)\n\nOptional Fields (when WithFilter=true):\n- filter (object): Entry/exit condition rules (complex nested structure)\n- updated (string): Last modification timestamp\n\nExample single object:\n\n{\n "id": "aud_1a2b3c4d5e6f",\n "name": "VIP Customers",\n "instance_id": "inst_abc123",\n "members": 1523,\n "subscribers": 1402,\n "created": "2024-01-15T10:30:00Z"\n}\n
• TotalCount (number): Total number of audiences matching the search criteria.
• SearchTerm (string): The search keyword used for filtering audiences.
• HasMore (bool): Boolean indicating if more pages of results are available.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Subscribe Audiences

Subscribe a list of contacts to a specific audience in Ortto. Use this to add or update contacts in bulk; for single contact updates consider 'Update Contact'.

Input Parameters:

• AudienceId: The ID of the audience to subscribe people to. How to obtain: 1. Via the 'Get Audiences' action (recommended). 2. From Ortto Audience URL: https://app.ortto.com/audiences/{audience_id}. Example: "65278392a1b2c3d4e5f6g7h8"
• PeopleData: List of people to subscribe. Key fields: 'email' (string): Contact email; 'external_id' (string): Your system's unique ID; 'subscribed' (boolean): Set to true to opt the contact into email marketing (permission-based), false keeps current state; 'sms_opted_in' (boolean): Set to true to grant permission for SMS marketing. Note: Setting these to true implies you have received explicit consent from the user. Example: [{"email": "john@example.com", "first_name": "John", "subscribed": true, "sms_opted_in": false}]

Options:

• AsyncProcessing: IMPORTANT: In async mode (true), the Results will show 'queued' status immediately. Actual processing happens in the background. If false, the request waits for completion. Default is true.
• MergeNested: Whether to merge nested objects (like addresses or custom attributes). If true, new data merges with existing records. If false, new data overwrites existing nested objects. Default is false.
• FindStrategy: Strategy used to identify existing contacts in Ortto. Options: 'email' (default): Match by email address. Use this when email is your primary identifier. 'external_id': Match by your system's unique ID. Use this when you have a stable external identifier and want to avoid issues if a user changes their email address. Default is 'email'.

Output:

• ProcessedCount (number): Number of contacts successfully processed for subscription status update.
• FailedCount (number): Number of contacts that failed to process.
• TotalCount (number): Total number of contacts in the request.
• AudienceId (string): The audience ID that was operated on.
• IsAsync (bool): Whether the processing was done asynchronously.
• Results (object-array): List of processing results for each person. Each object contains: email (string): Contact email; status (string): Processing status. Complete list of values: 'queued' (accepted for async processing), 'subscribed' (successfully opted-in), 'unsubscribed' (opted-out), 'suppressed' (blocked/blacklisted), 'error' (processing failed); error (string): Detailed error message if status is 'error', otherwise empty; person_id (string): Unique identifier in Ortto. Example: [{"email": "user@example.com", "status": "queued", "error": "", "person_id": "per_123"}, {"email": "invalid-email", "status": "error", "error": "Invalid email format", "person_id": ""}]
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200 for success, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Create Activities

Create a new custom activity definition in Ortto. Use this to define a new type of activity; for creating actual activity events, use 'Create Activity Event'.

Input Parameters:

• Name: The name of the activity definition. Must be unique within the account. Example: "Product Purchased"

Options:

• IconId: The visual icon associated with this activity. Recommended values: moneys-illustration-icon (Money bag for purchases), calendar-illustration-icon (Calendar for bookings), coupon-illustration-icon (Coupon/tag for promotions), email-illustration-icon (Email envelope for communications), happy-illustration-icon (Smiley face for general activities). Example: "moneys-illustration-icon"
• AdditionalFields: Advanced configuration. Supported keys: track_conversion_value (bool): Enable ROI tracking; touch (bool): Update 'Last Seen'; filterable (bool): Allow filtering; visible_in_feeds (bool): Show in feed; attributes (array): List of custom attributes. Each attribute requires: name (string) and display_type (string). Supported display_type values: "text", "number", "currency", "date", "boolean", "url". Example: {"track_conversion_value": true, "attributes": [{"name": "product_name", "display_type": "text"}]}

Output:

• Activity (object): The complete activity definition object. Key fields: activity_field_id (string): Unique identifier in format 'act::custom::{name-slug}'; name (string): Display name; state (string): Lifecycle state (draft, live, archived); icon_id (string): Visual icon ID; display_mode (object): UI rendering config with icon and color; attributes (array): List of custom attribute definitions containing name, display_type, and field_id. Refer to Ortto API documentation for full field list.
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 201 for created, 400 for bad request). Default 0 means no HTTP request was made.
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors reflected in ErrorMessage), 500 = system error (network failure, timeout, code crash), -1 = parameter validation error (request not sent).
• ErrorMessage (string): Error description message. Empty string if the operation completed successfully. Contains specific error details when StatusCode is non-200 or when the upstream API returns a business error.

Create Activities Event

Create custom activity events in Ortto. Use this to track user actions (e.g., 'product-viewed') and associate them with contacts.

Input Parameters:

• Activities: An array of activity objects (object-array type, NOT a JSON string). Maximum 100 activities per request. Each activity object must include:\n\nRequired Structure (as native object-array):\n- activity_id (string): Activity type identifier with 'act::' prefix (e.g., 'act::product-viewed')\n- attributes (object): Custom properties for this activity instance\n- fields (object): Contact fields to identify/update the person\n\nExample element:\n{\n "activity_id": "act::product-viewed",\n "attributes": {"str::product-name": "Laptop"},\n "fields": {"str::email": "user@example.com"}\n}

Options:

• MergeBy: Fields used to find and match existing contacts in Ortto (like a lookup key). Ortto requires a special format with prefixes to indicate field types.\n\nFormat: '::'\n- 'str::' = Text fields (e.g., email, external_id)\n- 'phn::' = Phone numbers\n- 'int::' = Numbers\n\nExamples:\n- Single field: 'str::email'\n- Multiple fields: 'str::email, phn::phone' (max 2 fields)\n\nNote: Spaces around commas are automatically trimmed. Providing more than 2 fields will result in a validation error (-1).
• MergeStrategy: Strategy for merging data into existing contact records. Default is 2.\n\nOptions:\n- 1 (Append Only): Only fill empty fields; do not overwrite existing data. Best for data enrichment.\n- 2 (Overwrite): Replace existing field values with new data. Recommended for CRM synchronization.\n- 3 (Ignore): Do not update existing records; only create new ones. Best for lead capture where existing data is protected.
• AsyncProcessing: Processing mode (also called 'background processing'). Default is False.\n- False (Synchronous / Wait for result): The request waits for Ortto to process the activities and returns immediate results.\n- True (Asynchronous / Background): The request returns immediately with a 'queued' status, and processing happens in the background.

Output:

• ProcessedCount (number): Number of activities successfully processed.
• FailedCount (number): Number of activities that failed to process.
• TotalCount (number): Total number of activities submitted for processing.
• IsAsync (bool): Whether the processing was done asynchronously.
• Activities (object-array): List of processing results for each submitted activity. Each object contains:\n\nCore Fields (always present):\n- person_id (string): Unique ID of the matched/created person\n- activity_id (string): ID of the created activity instance\n- status (string): Processing status ('ingested', 'queued', 'failed')\n- person_status (string): Person record status ('identified', 'anonymous', 'created', 'updated')\n\nOptional Fields (may appear):\n- created_at (string): ISO 8601 timestamp\n- error_message (string): Error details if status is 'failed'
• OriginalStatusCode (number): The raw HTTP status code returned by the Ortto API (e.g., 200, 201, 202).
• StatusCode (number): System operation status code. 200 = system healthy (including API business errors), 500 = system error, -1 = parameter validation error.
• ErrorMessage (string): Error description if operation fails, empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow to upsert people into your Ortto account.

The workflow consists of: Start -> Ortto -> Answer.

1. Add the Tool Node:
   • On the workflow canvas, click the "+" icon to add a new node.
   • Select the "Tools" tab in the panel.
   • Find and select Ortto from the tool list.
   • Choose the Upsert People action from the supported operations.
2. Configure the Node:
   • Click on the newly added Upsert People node to open its configuration panel on the right.
   • Credentials: At the top of the panel, select your configured Ortto credentials from the dropdown menu.
   • Input Parameters:
   • PeopleData: Enter the list of people you want to create or update. For example, [{"str::email": "john.doe@example.com", "str::first-name": "John"}].
   • MergeBy: Enter the field IDs to use for matching existing people. For example, ["str::email"].
3. Run and Verify:
   • Once all required parameters are filled, any error indicators on the node will disappear.
   • Click the "Test Run" button in the top right corner of the canvas.
   • After a successful execution, you can click the log icon to view the detailed input and output, verifying that the contacts were successfully upserted.

After completing these steps, your workflow is ready. Clicking "Test Run" will execute the batch upsert operation in your Ortto account.

6. FAQs

Q: I am getting a 401 or 403 error. What should I do?

A: Please check the following:

• API Key: Ensure your Ortto API key is valid and has not expired.
• Permissions: Verify that your API key has the necessary scopes and permissions to perform the requested actions (e.g., reading or writing contacts).

Q: Why are my contacts not being updated during an Upsert operation?

A: Please check the following:

• MergeBy Fields: Ensure the MergeBy parameter correctly identifies the existing records (e.g., using str::email).
• MergeStrategy: Verify that MergeStrategy is set to overwrite (0) or append (1) rather than ignore (2).

Q: What should I do if I get a validation error (-1)?

A: Please check the following:

• Required Fields: Ensure all required input parameters are provided.
• Field Formats: Double-check that you are using the correct field prefixes (e.g., str::, int::) when specifying custom fields.

7. Official Documentation

Ortto Official API Documentation