{"openapi":"3.1.0","info":{"title":"Events","description":"Automate payments across banks with a single API","version":"1","contact":{"name":"API Support","email":"dev@numeral.io"}},"tags":[{"name":"Events","description":"Events endpoints"},{"name":"Webhooks","description":"Webhooks endpoints"}],"servers":[{"url":"https://sandbox.numeral.io/v1"}],"components":{"securitySchemes":{"sec0":{"type":"apiKey","in":"header","name":"x-api-key"}},"parameters":{"list.common_parameters.sort_order":{"name":"sort_order","in":"query","description":"Order is based on attribute `created_at`. If `asc`, results are fetched in chronological order. If `desc`, results are fetched in reversed chronological order. Default order is `desc`.\n","schema":{"type":"string","enum":["asc","desc"]}}},"schemas":{"error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reason":{"type":"string"}}}},"correlation_id":{"type":"string"}}},"webhook":{"type":"object","properties":{"id":{"type":"string","description":"The ID of the webhook.","example":"3ee02261-be3b-46a2-addf-62813c49d5af"},"name":{"type":"string","description":"The name of the webhook.","example":"Payment orders webhook"},"notification_email":{"type":"string","description":"The email address notified when events fail to be delivered to the webhook. Empty if none is configured.","example":"dev@acme.com"},"url":{"type":"string","description":"The URL events are sent to.","example":"https://api.acme.com/numeral/webhooks"},"status":{"type":"string","description":"The status of the webhook. Events are only sent to `enabled` webhooks.","enum":["enabled","disabled"],"example":"enabled"},"rules":{"type":"object","description":"The events sent to the webhook, as a map of event topic to the list of event types. `*` matches all topics or all types.","additionalProperties":{"type":"array","items":{"type":"string"}},"example":{"payment_order":["approved","executed"],"file":["rejected"]}},"requires_response":{"type":"boolean","description":"Whether the webhook is expected to acknowledge events with a response body.","example":false},"fifo":{"type":"boolean","description":"Whether events are delivered to the webhook in order (first in, first out). When `true`, a failed event blocks the delivery of subsequent events until it is retried successfully.","example":true},"batching_size":{"type":"integer","description":"The maximum number of events sent in a single request to the webhook. `1` means events are sent individually.","example":1},"is_blocked":{"type":"boolean","description":"Whether event delivery to the webhook is blocked. Only applicable to FIFO webhooks (`fifo` is `true`), always `false` otherwise. Set to `true` when an event fails after all retries have been exhausted, and reset to `false` once the failed events have been retried successfully, for example with `POST /events/retry_failed`. Poll this attribute to monitor the delivery health of your webhooks.","example":false},"created_at":{"type":"string","description":"The creation date of the webhook.","example":"2022-11-03T12:20:07.00000002Z"}}}},"responses":{"errors.400.validation":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/error"}}}},"errors.404.not_found":{"description":"The specified resource was not found."}}},"security":[{"sec0":[]}],"paths":{"/events/retry_failed":{"post":{"summary":"Retry failed events","description":"Retry events that are in either `failed` status (events that have undergone 5 unsuccessful retries) or in `pending_retry` status (events that have experienced at least one failure but fewer than 5 failed retries). This process will reset these events, enabling immediate retry.","operationId":"retry-failed-events","tags":["Events"],"responses":{"200":{"description":"Failed events successfully retried.","content":{"application/json":{"examples":{"Result":{"value":{}}},"schema":{"type":"object","properties":{}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/events":{"get":{"summary":"List events","description":"List and filter events.","operationId":"list-events","tags":["Events"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","format":"int32","default":25}},{"name":"starting_after","in":"query","description":"The ID of the object from which your list request will start. It is not included in the result.","schema":{"type":"string"}},{"$ref":"#/components/parameters/list.common_parameters.sort_order"},{"name":"status","in":"query","description":"The status of the event.","schema":{"type":"string","enum":["created","delivered","pending_retry","failed","archived"]}},{"name":"topic","in":"query","description":"The topic of the event.","schema":{"type":"string"}},{"name":"type","in":"query","description":"The type of the event.","schema":{"type":"string"}},{"name":"related_object_id","in":"query","description":"The ID of the object related to the event.","schema":{"type":"string"}},{"name":"webhook_id","in":"query","description":"The ID of the webhook that received the event.","schema":{"type":"string"}},{"name":"start_date","in":"query","description":"The creation date of the event.","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"The creation date of the event.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"List of filtered events.","content":{"application/json":{"examples":{"Result":{"value":{"records":[{"id":"65dc3efd-23f2-4244-af2b-dadf77055749","object":"event","topic":"payment_order","type":"pending_approval","data":{"id":"1f523326-bf5a-49ce-abc8-ff8db31d6bed","type":"sepa","amount":5000,"object":"payment_order","status":"pending_approval","purpose":"","currency":"EUR","metadata":{},"approvals":null,"bank_data":{"file_id":"","message_id":"","end_to_end_id":"1f523326bf5a49ceabc8ff8db31d6bed","transaction_id":"1f523326bf5a49ceabc8ff8db31d6bed","original_instruction_id":"1f523326bf5a49ceabc8ff8db31d6bed"},"direction":"credit","reference":"Payment 1bb91df5b7","created_at":"2025-03-12T10:10:42.71976Z","created_by":{"id":"2c84f1cf-4517-4e5c-a248-5ea87cc9ec2e","type":"api_key"},"fee_option":"","value_date":"","auto_approval":false,"custom_fields":{},"retry_details":null,"status_details":"","idempotency_key":"","payment_file_id":"","treasury_option":"","connected_account":"2c84f1cf-4517-4e5c-a248-5ea87cc9ec1d","receiving_account":{"bank_code":"URNSFRPP","holder_name":"Turing Account","account_number":"FR7712739000308574529483F84","holder_address":{"city":"Paris","line_1":"1, rue de Londres","line_2":"","country":"FR","postal_code":"75009","street_name":"","region_state":"Ile-de-France","building_number":""}},"reconciled_amount":0,"originating_account":{"bank_code":"SOMEBIC0XXX","holder_name":"Numeral","account_number":"3809","holder_address":{"city":"London","line_1":"1 rue des Huns","line_2":"","country":"GB","postal_code":"75000","street_name":"","region_state":"Île-de-France","building_number":""},"creditor_identifier":""},"ultimate_originator":{"holder_name":"","holder_address":null,"organization_identification":null},"ultimate_receiver":{"holder_name":"","holder_address":null,"organization_identification":null},"connected_account_id":"2c84f1cf-4517-4e5c-a248-5ea87cc9ec1d","direct_debit_mandate":null,"receiving_account_id":"","reconciliation_status":"unreconciled","confidentiality_option":"","originating_account_id":"","direct_debit_mandate_id":"","requested_execution_date":"","payment_approval_rule_ids":null},"status":"created","status_details":"","related_object_id":"1f523326-bf5a-49ce-abc8-ff8db31d6bed","related_object_type":"payment_order","created_at":"2025-03-12T10:10:42.798245364Z"}]}}},"schema":{"type":"object","properties":{"id":{"type":"string","example":"7c7c189f-8520-48f9-8ab8-9f6384509eba"},"object":{"type":"string","example":"event"},"created_at":{"type":"string","example":"2021-01-01T00:11:07Z"},"topic":{"type":"string","example":"payment_order"},"type":{"type":"string","example":"approved"},"status":{"type":"string","example":"delivered"},"status_details":{},"data":{"type":"object","properties":{"id":{"type":"string","example":"9482351c-9a4c-45d9-8fa8-50a50843e593"},"object":{"type":"string","example":"payment_order"},"connected_account_id":{"type":"string","example":"050b18a2-fe5a-47c5-8692-50cf6663c259"},"type":{"type":"string","example":"sepa"},"direction":{"type":"string","example":"credit"},"amount":{"type":"integer","example":10000,"default":0},"currency":{"type":"string","example":"eur"},"status":{"type":"string","example":"approved"},"origin":{"type":"object","properties":{"account_number":{"type":"string","example":"FR7630004000031234567890143"},"bank_code":{"type":"string","example":"BNPAFRPPXXX"},"holder_name":{"type":"string","example":"Acme Corporation"},"holder_address":{"type":"string","example":"1, rue de la Paix, 75002 Paris, France"}}},"destination":{"type":"object","properties":{"account_number":{"type":"string","example":"FR7630056009271234567890182"},"bank_code":{"type":"string","example":"CCBPFRPPMTZ"},"holder_name":{"type":"string","example":"Jane Doe"},"holder_address":{"type":"string","example":"1, avenue des Champs Elysées, 75008 Paris, France"}}},"purpose":{"type":"string","example":"Lorem ipsum dolor sit amet"},"metadata":{"type":"object","properties":{}},"created_at":{"type":"string","example":"2021-01-01T00:11:07Z"}}}}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/events/{id}":{"get":{"summary":"Retrieve event","description":"Retrieve the details of an event.","operationId":"retrieve-event","tags":["Events"],"parameters":[{"name":"id","in":"path","description":"The ID of the event.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successfully retrieved event.","content":{"application/json":{"examples":{"Result":{"value":{"id":"65dc3efd-23f2-4244-af2b-dadf77055749","object":"event","topic":"payment_order","type":"pending_approval","data":{"id":"1f523326-bf5a-49ce-abc8-ff8db31d6bed","type":"sepa","amount":5000,"object":"payment_order","status":"pending_approval","purpose":"","currency":"EUR","metadata":{},"approvals":null,"bank_data":{"file_id":"","message_id":"","end_to_end_id":"1f523326bf5a49ceabc8ff8db31d6bed","transaction_id":"1f523326bf5a49ceabc8ff8db31d6bed","original_instruction_id":"1f523326bf5a49ceabc8ff8db31d6bed"},"direction":"credit","reference":"Payment 1bb91df5b7","created_at":"2025-03-12T10:10:42.71976Z","created_by":{"id":"2c84f1cf-4517-4e5c-a248-5ea87cc9ec2e","type":"api_key"},"fee_option":"","value_date":"","auto_approval":false,"custom_fields":{},"retry_details":null,"status_details":"","idempotency_key":"","payment_file_id":"","treasury_option":"","connected_account":"2c84f1cf-4517-4e5c-a248-5ea87cc9ec1d","receiving_account":{"bank_code":"URNSFRPP","holder_name":"Turing Account","account_number":"FR7712739000308574529483F84","holder_address":{"city":"Paris","line_1":"1, rue de Londres","line_2":"","country":"FR","postal_code":"75009","street_name":"","region_state":"Ile-de-France","building_number":""}},"reconciled_amount":0,"originating_account":{"bank_code":"SOMEBIC0XXX","holder_name":"Numeral","account_number":"3809","holder_address":{"city":"London","line_1":"1 rue des Huns","line_2":"","country":"GB","postal_code":"75000","street_name":"","region_state":"Île-de-France","building_number":""},"creditor_identifier":""},"ultimate_originator":{"holder_name":"","holder_address":null,"organization_identification":null},"ultimate_receiver":{"holder_name":"","holder_address":null,"organization_identification":null},"connected_account_id":"2c84f1cf-4517-4e5c-a248-5ea87cc9ec1d","direct_debit_mandate":null,"receiving_account_id":"","reconciliation_status":"unreconciled","confidentiality_option":"","originating_account_id":"","direct_debit_mandate_id":"","requested_execution_date":"","payment_approval_rule_ids":null},"status":"created","status_details":"","related_object_id":"1f523326-bf5a-49ce-abc8-ff8db31d6bed","related_object_type":"payment_order","created_at":"2025-03-12T10:10:42.798245364Z"}}},"schema":{"type":"object","properties":{}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/events/{id}/resend":{"post":{"summary":"Resend event","description":"Resend an event already delivered to one or multiple webhooks.","operationId":"resend-event","tags":["Events"],"parameters":[{"name":"id","in":"path","description":"The ID of the event.","schema":{"type":"string"},"required":true}],"requestBody":{"description":"An optional list of webhook IDs to resend the event to. If not provided, the event will be resent to the webhooks it was originally sent to.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook_ids":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Event successfully resent.","content":{"application/json":{"examples":{"Result":{"value":{"webhooks":[{"webhook_id":"3ee02261-be3b-46a2-addf-62813c49d5af","status":"delivered","status_details":""}],"summary":{"total_items":1,"total_successful":1,"total_failed":0}}}},"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"type":"object","properties":{"webhook_id":{"type":"string"},"status":{"type":"string"},"status_details":{"type":"string"}}}},"summary":{"type":"object","properties":{"total_items":{"type":"integer"},"total_successful":{"type":"integer"},"total_failed":{"type":"integer"}}}}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}},"/webhooks":{"get":{"summary":"List webhooks","description":"List and filter the webhooks of your legal entity. This endpoint is not paginated, all matching webhooks are returned in `records`.","operationId":"list-webhooks","tags":["Webhooks"],"parameters":[{"name":"status","in":"query","description":"The status of the webhook.","schema":{"type":"string","enum":["enabled","disabled"]}}],"responses":{"200":{"description":"List of filtered webhooks.","content":{"application/json":{"examples":{"Result":{"value":{"records":[{"id":"3ee02261-be3b-46a2-addf-62813c49d5af","name":"Payment orders webhook","notification_email":"dev@acme.com","url":"https://api.acme.com/numeral/webhooks","status":"enabled","rules":{"payment_order":["approved","executed"],"file":["rejected"]},"requires_response":false,"fifo":true,"batching_size":1,"is_blocked":false,"created_at":"2022-11-03T12:20:07.00000002Z"}]}}},"schema":{"type":"object","properties":{"records":{"type":"array","items":{"$ref":"#/components/schemas/webhook"}}}}}}},"400":{"$ref":"#/components/responses/errors.400.validation"}}}},"/webhooks/{id}":{"get":{"summary":"Retrieve webhook","description":"Retrieve the details of a webhook.","operationId":"retrieve-webhook","tags":["Webhooks"],"parameters":[{"name":"id","in":"path","description":"The ID of the webhook.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Successfully retrieved webhook.","content":{"application/json":{"examples":{"Result":{"value":{"id":"3ee02261-be3b-46a2-addf-62813c49d5af","name":"Payment orders webhook","notification_email":"dev@acme.com","url":"https://api.acme.com/numeral/webhooks","status":"enabled","rules":{"payment_order":["approved","executed"],"file":["rejected"]},"requires_response":false,"fifo":true,"batching_size":1,"is_blocked":false,"created_at":"2022-11-03T12:20:07.00000002Z"}}},"schema":{"$ref":"#/components/schemas/webhook"}}}},"400":{"$ref":"#/components/responses/errors.400.validation"},"404":{"$ref":"#/components/responses/errors.404.not_found"}}}}}}