{"openapi":"3.1.0","info":{"title":"Ringmaster ingest API","version":"1","description":"Send profiles, events, suppressions and opt-in subscriptions to Ringmaster. Guide: /docs/api"},"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An ingest API key (rm_live_…) from Settings, API keys in the Ringmaster console."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"],"additionalProperties":false}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/events":{"post":{"operationId":"trackEvents","summary":"Track events","description":"Records one event, or up to 100 as { events: [...] }. Each event creates or updates its profile first, merging properties key by key.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"event":{"type":"string","minLength":1,"maxLength":255,"description":"The event name, such as register"},"profile":{"type":"object","properties":{"email":{"description":"Leave out to keep the stored email; null clears it","anyOf":[{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"properties":{"description":"Merged into the stored properties key by key","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code"},{"type":"null"}]},"timezone":{"anyOf":[{"description":"IANA time zone","type":"string"},{"type":"null"}]},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the person, such as your user id"}},"required":["id"],"additionalProperties":false},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"occurredAt":{"description":"When it happened; defaults to when Ringmaster received it","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["event","profile"],"additionalProperties":false},{"type":"object","properties":{"events":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"event":{"type":"string","minLength":1,"maxLength":255,"description":"The event name, such as register"},"profile":{"type":"object","properties":{"email":{"description":"Leave out to keep the stored email; null clears it","anyOf":[{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"properties":{"description":"Merged into the stored properties key by key","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code"},{"type":"null"}]},"timezone":{"anyOf":[{"description":"IANA time zone","type":"string"},{"type":"null"}]},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the person, such as your user id"}},"required":["id"],"additionalProperties":false},"properties":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"occurredAt":{"description":"When it happened; defaults to when Ringmaster received it","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["event","profile"],"additionalProperties":false}}},"required":["events"],"additionalProperties":false}]},"example":{"event":"register","profile":{"id":"user_8f2c","email":"jane@example.com","properties":{"first_name":"Jane","wedding_date":"2027-06-12"},"country":"US","timezone":"America/New_York"},"properties":{"source":"signup_form"},"occurredAt":"2026-10-29T12:00:00Z"}}}},"responses":{"202":{"description":"Stored","content":{"application/json":{"schema":{"type":"object","properties":{"accepted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["accepted"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/profiles/{id}":{"put":{"operationId":"upsertProfile","summary":"Create or update a profile","description":"Creates the profile with your id, or updates it. Fields you leave out keep their stored value.","parameters":[{"name":"id","in":"path","required":true,"description":"Your own id for the person, such as your user id","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the person, such as your user id"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"description":"Leave out to keep the stored email; null clears it","anyOf":[{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"properties":{"description":"Merged into the stored properties key by key","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code"},{"type":"null"}]},"timezone":{"anyOf":[{"description":"IANA time zone","type":"string"},{"type":"null"}]}},"additionalProperties":false},"example":{"email":"jane@example.com","properties":{"plan":"free"}}}}},"responses":{"200":{"description":"Stored","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"}},"required":["created"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"eraseProfile","summary":"Erase a profile","description":"Deletes the profile and everything Ringmaster holds about it, for a GDPR erasure request. The audit log records the erasure without the email. Suppressions stay, because they are keyed by email.","parameters":[{"name":"id","in":"path","required":true,"description":"Your own id for the person, such as your user id","schema":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the person, such as your user id"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Erased, or there was nothing to erase","content":{"application/json":{"schema":{"type":"object","properties":{"erased":{"type":"boolean"}},"required":["erased"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions":{"post":{"operationId":"suppress","summary":"Suppress an email address","description":"Stops Ringmaster mailing the address in one topic or, with no topic, in every opt-out and opt-in topic. Use it when the person unsubscribes elsewhere. A service topic cannot be suppressed: only a bounce or a complaint stops one.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"topic":{"description":"A topic's key. Leave out to suppress every topic","anyOf":[{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"The topic's key, such as product-news"},{"type":"null"}]}},"required":["email"],"additionalProperties":false},"example":{"email":"jane@example.com"}}}},"responses":{"200":{"description":"Suppressed. created is false when this suppression was already there","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"}},"required":["created"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/suppressions/{email}":{"delete":{"operationId":"liftSuppression","summary":"Lift a suppression","description":"Removes the unsubscribes your app or the person made for the address and topic, or the every-topic ones with no topic. Suppressions made in the console, bounces and complaints stay. URL-encode the address.","parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},{"name":"topic","in":"query","required":false,"description":"A topic's key. Leave out to lift the every-topic suppression","schema":{"description":"A topic's key. Leave out to lift the every-topic suppression","type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Lifted, or there was nothing to lift","content":{"application/json":{"schema":{"type":"object","properties":{"lifted":{"type":"boolean"}},"required":["lifted"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscriptions":{"post":{"operationId":"subscribe","summary":"Record opt-in consent","description":"Records that the person agreed to an opt-in topic, with the evidence you collected. An opt-in topic mails only subscribers. A suppression still stops the topic; lift it as well when the new consent should override it. A repeat keeps the first record. A new subscription whose consentedAt is within the last day enrolls each profile with the address in the flows that start on subscribing to the topic, so send the profile first; an older one is treated as a backfill and enrolls no one.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"topic":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"An opt-in topic's key"},"source":{"default":"api","description":"Where the person agreed, such as signup_form","type":"string","minLength":1,"maxLength":100},"consentedAt":{"description":"When the person agreed; defaults to when Ringmaster received it","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"ip":{"description":"The IP address the person agreed from","anyOf":[{"type":"string","format":"ipv4","pattern":"^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"},{"type":"string","format":"ipv6","pattern":"^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$"}]},"userAgent":{"description":"The browser the person agreed from","type":"string","maxLength":1000}},"required":["email","topic"],"additionalProperties":false},"example":{"email":"jane@example.com","topic":"newsletter","source":"signup_form","consentedAt":"2026-10-29T12:00:00Z","ip":"203.0.113.7","userAgent":"Mozilla/5.0"}}}},"responses":{"200":{"description":"Recorded. created is false when the person was already subscribed","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"boolean"}},"required":["created"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/subscriptions/{email}":{"delete":{"operationId":"unsubscribe","summary":"Withdraw opt-in consent","description":"Removes the person's subscription to an opt-in topic. URL-encode the address.","parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},{"name":"topic","in":"query","required":true,"description":"An opt-in topic's key","schema":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"An opt-in topic's key"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"responses":{"200":{"description":"Removed, or there was nothing to remove","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean"}},"required":["removed"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/enrollments":{"post":{"operationId":"enroll","summary":"Enroll a profile in a flow","description":"Enrolls the profile in an active flow now, without waiting for its trigger event, for a one-off or a backfill. The profile is created or updated first. The flow's reentry rule and the person's consent still apply, so the answer says whether the profile was enrolled and, if not, why: already_active, reentry (the rule refused it), no_key (the flow enters per event property and properties lacks it), entry (the profile does not meet the flow's entry conditions), exclusive (the flow runs one marketing flow at a time and the profile is in another), consent_blocked or no_email. The properties stand in for the trigger event's in the flow's emails.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable across every retry of one request, such as the id of the outbox row that carries it. A repeat with the same body gets the first answer again; a different request with it gets 409. Kept for 7 days.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"flow":{"type":"string","maxLength":64,"pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","description":"The flow's key, such as welcome"},"profile":{"type":"object","properties":{"email":{"description":"Leave out to keep the stored email; null clears it","anyOf":[{"type":"string","maxLength":320,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"properties":{"description":"Merged into the stored properties key by key","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO 3166-1 alpha-2 country code"},{"type":"null"}]},"timezone":{"anyOf":[{"description":"IANA time zone","type":"string"},{"type":"null"}]},"id":{"type":"string","minLength":1,"maxLength":255,"description":"Your own id for the person, such as your user id"}},"required":["id"],"additionalProperties":false},"properties":{"description":"Read as event.properties in the flow's emails","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["flow","profile"],"additionalProperties":false},"example":{"flow":"welcome","profile":{"id":"user_8f2c","email":"jane@example.com","properties":{"first_name":"Jane","wedding_date":"2027-06-12"},"country":"US","timezone":"America/New_York"},"properties":{"source":"backfill"}}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"type":"object","properties":{"enrolled":{"type":"boolean"},"enrollment":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string","enum":["already_active","reentry","no_key","entry","exclusive","consent_blocked","no_email"]},{"type":"null"}]}},"required":["enrolled","enrollment","reason"],"additionalProperties":false}}}},"400":{"description":"No Idempotency-Key, or a body that is not JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"No API key, or one that is unknown or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The Idempotency-Key was used for a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The body is over 256 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The request does not match the schema, and issues lists each problem; or it names a topic or flow the organization does not have, a topic of the wrong kind, or a flow that is not active","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Ringmaster failed; retry with the same Idempotency-Key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}