Integration Actions Execute operations on connected integrations like Salesforce, Marketo, and HubSpot through a unified API.
Perform operations on connected integrations through the Oktopost API. This endpoint provides a unified interface to execute actions on Salesforce, Marketo, and HubSpot integrations.
The integration must have a valid status and be enabled before actions can be executed. Use the Integrations endpoint to verify integration state.
Execute an action on a connected integration. The available actions depend on the integration type.
Parameter Type Required Description id String Yes The Integration ID (15 characters, e.g. 014000000000001). actionName String Yes The action name. Must be a supported action for the integration type. payload JSON No JSON-encoded object containing action-specific parameters. Default:
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000001" \ -d actionName="contact.getByEmail" \ -d payload='{"email":"john@example.com"}' { "Result" : true , "IntegrationAction" : { "Id" : "12345" , "Email" : "john@example.com" , "FirstName" : "John" , "LastName" : "Doe" } } { "Result" : false , "Errors" : [ "Missing required field: email" ] }
Salesforce — Leads, Contacts, Accounts, Tasks, Cases, Case CommentsMarketo — Lists, Leads, Custom ActivitiesHubSpot — Contacts, Timeline Events
Action Description Payload Fields lead.getByIdGet a lead by Salesforce ID id (string, required)lead.getByEmailGet a lead by email address email (string, required)lead.searchSearch leads by keyword search (string, required)lead.createCreate a new lead data (object, required) — field/value pairslead.updateUpdate an existing lead id (string, required), data (object, required)
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000001" \ -d actionName="lead.create" \ -d payload='{"data":{"LastName":"Doe","Company":"Acme","Email":"john@acme.com"}}' Action Description Payload Fields contact.getByIdGet a contact by Salesforce ID id (string, required)contact.getByEmailGet a contact by email address email (string, required)contact.searchSearch contacts by keyword search (string, required)contact.createCreate a new contact data (object, required) — field/value pairscontact.updateUpdate an existing contact id (string, required), data (object, required)
Action Description Payload Fields account.getByIdGet an account by Salesforce ID id (string, required)account.createCreate a new account data (object, required) — field/value pairsaccount.updateUpdate an existing account id (string, required), data (object, required)account.deleteDelete an account id (string, required)
Action Description Payload Fields task.createCreate a new task data (object, required) — field/value pairs
Action Description Payload Fields case.getByIdGet a case by Salesforce ID id (string, required)case.getAllGet all cases (none) case.createCreate a new case data (object, required) — field/value pairscase.updateUpdate an existing case id (string, required), data (object, required)
Action Description Payload Fields caseComment.getByIdGet a comment by ID id (string, required)caseComment.getByCaseIdGet all comments for a case caseId (string, required)caseComment.createAdd a comment to a case caseId (string, required), data (object, required)caseComment.updateUpdate a case comment caseId (string, required), commentId (string, required), data (object, required)
For Salesforce create and update actions, the data object should contain Salesforce field API names as keys. Required fields depend on your Salesforce org configuration.
Action Description Payload Fields list.getAllGet all static lists (none) list.addLeadsAdd leads to a static list listId (string, required), leadIds (array of integers, required)
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000002" \ -d actionName="list.addLeads" \ -d payload='{"listId":"1234","leadIds":[100,200,300]}' Action Description Payload Fields lead.createUpdateCreate or update a lead email (string, required), data (object, required) — attributes to synclead.createCreate a new lead data (object, required) — see supported fields below
Supported fields for lead.create:
Email, Company, FirstName, LastName, Phone, StreetAddress, City, State, Country, ZipCode, JobTitle, WorkPhone, WorkEmail
Custom fields (ending in __c) are automatically matched against your Marketo instance schema.
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000002" \ -d actionName="lead.create" \ -d payload='{"data":{"Email":"john@acme.com","FirstName":"John","LastName":"Doe","Company":"Acme"}}' Action Description Payload Fields activity.addCustomAdd a custom activity leadId (integer, required), activityTypeId (integer, required), primaryAttributeValue (string, required)
Optional fields for activity.addCustom:
Field Type Description attributesObject Associative object of {fieldName: value} pairs for activity attributes activityDateString ISO 8601 date string. Defaults to current time if omitted.
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000002" \ -d actionName="activity.addCustom" \ -d payload='{"leadId":12345,"activityTypeId":100001,"primaryAttributeValue":"https://example.com/post","attributes":{"postUrl":"https://example.com/post","network":"LinkedIn"}}' Action Description Payload Fields contact.getByEmailLook up a contact by email email (string, required)contact.getByIdLook up a contact by HubSpot ID id (string, required)contact.createCreate a new contact data (object, required) — property/value pairs
For HubSpot contact lookups (contact.getByEmail, contact.getById), a null contact is returned when no match is found — this is not treated as an error.
Property names for contact.create must use HubSpot's internal lowercase names: email, firstname, lastname, company, phone, website, etc.
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000003" \ -d actionName="contact.create" \ -d payload='{"data":{"email":"john@acme.com","firstname":"John","lastname":"Doe","company":"Acme"}}' { "Result" : true , "IntegrationAction" : { "contact" : null } } Action Description Payload Fields event.upsertCreate or update a timeline event id (string, required), eventTypeId (string, required), email (string, required)
Optional fields for event.upsert:
Field Type Description extraDataObject Additional data to attach to the event propertiesObject Token values for the event template
curl https://api.oktopost.com/v2/integration-action -X POST \ -d id="014000000000003" \ -d actionName="event.upsert" \ -d payload='{"id":"evt-001","eventTypeId":"12345","email":"john@acme.com","properties":{"postTitle":"My Post"}}' The endpoint validates in the following order:
Permission — The API key must have the Integration Add permission.Integration — The integration must exist and belong to the authenticated account.Status — The integration status must be valid.State — The integration state must be enabled.Integration type — The integration type must be supported (salesforce, marketo, hubspot).Action — The action must be valid for the integration type.Payload — All required fields for the action must be present and non-empty.
HTTP Code Condition 400 Invalid payload, unsupported action, validation failure, or integration action error 401 Authentication failed (invalid API credentials or expired integration token) 404 Integration not found or does not belong to account 500 Unexpected server error
