Reference

Push an order to a CRM

POST /v1/orders/{id}/pushes. Push an order's records to a connection, keyed on mydatahub_record_id with the MyDataHub property group.

Generated from the contractsView as Markdown

POST /v1/orders/{id}/pushes

Push an order's records to a connection, keyed on mydatahub_record_id with the MyDataHub property group. dry_run defaults to true and reports what would change. A live push needs approval: a person's confirmation_token (or MCP elicitation), or an agent key whose allowed_tools include push_to_crm and whose allowed_connection_ids include the connection; otherwise 403 confirmation-required. Records only: nothing is ever sent to the contacts. Free.

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/orders/{id}/pushes`
Operation id	`createPush`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `pushes:write`.
Idempotency-Key	Optional. Makes a retry safe.
MCP tool	`push_to_crm`
Tag	CRM push

Request

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`MyDataHub-Version`	header	string	no	The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.
`Idempotency-Key`	header	string	no	Makes the request safe to retry: the same key returns the stored response. Keys are kept for the life of the organisation.

Body

Member	Type	Required	Description
`connection_id`	string	yes	Format: a CRM connection id: conn_ followed by a 26 character ULID in upper case Crockford base32, such as conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G.
`dry_run`	boolean	no	Default true: report what would change without writing. A live push needs approval: a person's confirmation, or an agent key allowed push_to_crm on this connection. Default `true`.
`update_existing`	boolean	no	Update records already in the CRM, matched on mydatahub_record_id. Default true. Default `true`.
`confirmation_token`	string	no	The token the approval page on mydatahub.emailmovers.com returns once the signed-in person approves. It is bound to that person (their sub), this spend (the machine quote_id, or the enrichment or push) and an expiry no later than the quote's, and it is redeemable once.

Example request

curl -X POST "https://mydatahub.emailmovers.com/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/pushes" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G"
}'

Responses

202: The push, or its dry run.

Headers: RateLimit, RateLimit-Policy, Location.

Member	Type	Always present	Description
`id`	string	yes	Format: a CRM push id: psh_ followed by a 26 character ULID in upper case Crockford base32, such as psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5.
`order_id`	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`connection_id`	string	yes	Format: a CRM connection id: conn_ followed by a 26 character ULID in upper case Crockford base32, such as conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G.
`dry_run`	boolean	yes
`status`	enum: `queued`, `running`, `completed`, `partial`, `failed`	yes
`summary`	object	yes
`summary.to_create`	integer (0 or more)	yes
`summary.to_update`	integer (0 or more)	yes
`summary.already_present`	integer (0 or more)	yes
`summary.skipped`	integer (0 or more)	yes
`summary.failed`	integer (0 or more)	yes
`property_group`	array of enum: `mydatahub_record_id`, `licence_expires_at`, `lawful_basis`, `article14_status`, `tps_ctps_screened_at`, `subscriber_class`, `suppression_status`, `compliance_receipt_url`	yes	The MyDataHub property group written on every record (CrmPropertyGroup).
`sample`	`CrmPropertyGroup` or null	yes	On a dry run: the property group the first record would carry.
`sample.mydatahub_record_id`	string	yes	The record id: a Salesforce External ID, a HubSpot unique property, a Pipedrive custom field.
`sample.licence_expires_at`	string (date) or null	yes
`sample.lawful_basis`	enum: `legitimate_interests_art6_1_f`	yes
`sample.article14_status`	enum: `notified`, `publicly_notified_disproportionate_effort`, `pending_within_window`	yes
`sample.tps_ctps_screened_at`	string (date) or null	yes
`sample.subscriber_class`	enum: `ltd`, `plc`, `llp`, `scottish_partnership`, `public_body`, `charity_incorporated`, `sole_trader`, `ordinary_partnership`, and 1 more	yes
`sample.suppression_status`	enum: `none`, `objected_to_emailmovers`, `objected_to_licensee`, `deceased`, `left_company`	yes	Kept current: an objection reaching the record updates it in the CRM.
`sample.compliance_receipt_url`	string (uri)	yes
`errors`	array of object	yes
`errors[].record_id`	string	yes
`errors[].message`	string	yes
`created_at`	string (date-time)	yes
`completed_at`	string (date-time) or null	yes

Example response

{
  "id": "psh_01JB4NC3W2X6Y7Z8A1B2C3D4E5",
  "order_id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E",
  "connection_id": "conn_01JB3Y2X6Y7Z8A1B2C3D4E5F6G",
  "dry_run": true,
  "status": "completed",
  "summary": {
    "to_create": 4102,
    "to_update": 0,
    "already_present": 0,
    "skipped": 0,
    "failed": 0
  },
  "property_group": [
    "mydatahub_record_id",
    "licence_expires_at",
    "lawful_basis",
    "article14_status",
    "tps_ctps_screened_at",
    "subscriber_class",
    "suppression_status",
    "compliance_receipt_url"
  ],
  "sample": {
    "mydatahub_record_id": "contact_01JA9X2V7XN3M9R6T1Y5W8ZAK8",
    "licence_expires_at": "2027-09-26",
    "lawful_basis": "legitimate_interests_art6_1_f",
    "article14_status": "notified",
    "tps_ctps_screened_at": "2026-09-12",
    "subscriber_class": "ltd",
    "suppression_status": "none",
    "compliance_receipt_url": "https://mydatahub.emailmovers.com/receipts/rcpt_01JB4NA2Q5W8ZAK8Q2V7XN3M9R"
  },
  "errors": [],
  "created_at": "2026-09-26T10:20:00Z",
  "completed_at": "2026-09-26T10:20:03Z"
}

Errors

Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).
403	`insufficient-scope`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.
404	`not-found`	No such object for this organisation.
409	`idempotency-key-reused`, `quote-expired`, `order-not-ready`, `order-not-cancellable`	An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state.
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.