{"openapi":"3.0.3","info":{"title":"Message status API","description":"API for querying SMS statistics and message details","version":"3.2.10.0"},"externalDocs":{"description":"Message Status API Documentation","url":"https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/apistatus-references"},"servers":[{"url":"https://sms-apistatus.test.namirialtsp.com/api","description":"Development and testing environment"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"MessageStatus","description":"Retrieve delivery status and statistics for SMS messages.\n\n**Authentication**: API Key required (`X-Api-Key` header)","externalDocs":{"description":"Message Status API Documentation","url":"https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/apistatus-references"}}],"paths":{"/messagestatus/phonenumber/{phonenumber}":{"get":{"tags":["MessageStatus"],"summary":"Get latest SMS from phone number","description":"Retrieves the delivery status of the latest messages sent to a given phone number.","operationId":"getLatestSmsFromNumber","parameters":[{"name":"phonenumber","in":"path","description":"Phone number in E.164 format (e.g., +1234567890).","required":true,"schema":{"type":"string","example":"+1234567890"}},{"name":"sendDate","in":"query","description":"Filter messages sent before this timestamp (ISO 8601 format, e.g. `2026-12-31T23:59:59Z`). Defaults to current time if not specified.","schema":{"type":"string","format":"date-time"}},{"name":"count","in":"query","description":"Maximum number of records to return (max 100)","schema":{"maximum":100,"minimum":1,"type":"integer","format":"int64","default":50}}],"responses":{"200":{"description":"SMS list for phone number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsStatisticsResponse"},"examples":{"withReference":{"summary":"Message with reference","description":"withReference","value":{"messages":[{"message":{"id":"54145623-7f65-4d02-b29d-106a42ca7a88","reference":{"service":"DIGITALSIGN","action":"AUTH","key":"ref-12345"},"channel":"SMS","status":"DELIVERED","providerAcceptanceAt":"2026-02-25T16:12:10Z","statusChangedAt":"2026-02-25T16:12:15Z","provider":{"name":"PROVIDER1","id":"DSFGDF5gw45g3453","status":"DELIVERED","code":"0"},"sms":{"segments":1}}}]}},"withoutReference":{"summary":"Message without reference (reference not specified in send request)","description":"withoutReference","value":{"messages":[{"message":{"id":"e989c2ec-c476-4224-a2b3-f21c76b552bb","reference":{},"channel":"SMS","status":"DELIVERED","providerAcceptanceAt":"2026-02-26T21:47:22Z","statusChangedAt":"2026-02-26T21:47:30Z","provider":{"name":"PROVIDER2","id":"381b43c9-fff1-cf1e-b15c-e8f387f2d49f","status":"DELIVERED","code":"0"},"sms":{"segments":1}}}]}},"emptyResult":{"summary":"No messages found","description":"emptyResult","value":{"messages":[]}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid-send-date":{"summary":"Invalid sendDate format","description":"invalid-send-date","value":{"error":{"code":4,"message":"Invalid sendDate format. Expected ISO 8601 (e.g. 2026-12-31T23:59:59Z)."}}},"count-out-of-range":{"summary":"count out of range","description":"count-out-of-range","value":{"error":{"code":5,"message":"Parameter \u0027count\u0027 must be between 1 and 100."}}}}}}},"401":{"description":"Unauthorized. Empty or missing api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":2,"message":"Empty or missing api-key"}}}}},"403":{"description":"Forbidden. Invalid path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":3,"message":"Invalid path"}}}}},"500":{"description":"Internal server error"}}}},"/messagestatus/reference/{referencekey}":{"get":{"tags":["MessageStatus"],"summary":"Get latest SMS from reference key","description":"Retrieves the delivery status of the latest messages associated with the external key specified in the `reference.key` parameter of the send API.","operationId":"getLatestSmsFromReferenceKey","parameters":[{"name":"referencekey","in":"path","description":"External key specified in the `reference.key` parameter of the send request.","required":true,"schema":{"type":"string","example":"ref-12345"}},{"name":"sendDate","in":"query","description":"Filter messages sent before this timestamp (ISO 8601 format, e.g. `2026-12-31T23:59:59Z`). Defaults to current time if not specified.","schema":{"type":"string","format":"date-time"}},{"name":"count","in":"query","description":"Maximum number of records to return (max 100)","schema":{"maximum":100,"minimum":1,"type":"integer","format":"int64","default":50}}],"responses":{"200":{"description":"SMS list for reference key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SmsStatisticsResponse"},"examples":{"withReference":{"summary":"Message with reference","description":"withReference","value":{"messages":[{"message":{"id":"54149766-7f65-4d02-b29d-406a42ca7a81","reference":{"service":"DIGITALSIGN","action":"AUTH","key":"ref-12345"},"channel":"SMS","status":"DELIVERED","providerAcceptanceAt":"2026-02-25T16:12:10Z","statusChangedAt":"2026-02-25T16:12:15Z","provider":{"name":"PROVIDER1","id":"eb1cd034767b91e5d7a1fd23d9f","status":"DELIVERED","code":"0"},"sms":{"segments":1}}}]}},"withoutReference":{"summary":"Message without reference (reference not specified in send request)","description":"withoutReference","value":{"messages":[{"message":{"id":"320bc578-d2f9-44e0-b83e-72cbb9dbd5da","reference":{},"channel":"SMS","status":"DELIVERED","providerAcceptanceAt":"2026-02-26T11:41:41Z","statusChangedAt":"2026-02-26T11:41:47Z","provider":{"name":"PROVIDER2","id":"0467bc0e-425e-2d1d-b159-91b17d93e401","status":"DELIVERED","code":"0"},"sms":{"segments":1}}}]}},"emptyResult":{"summary":"No messages found","description":"emptyResult","value":{"messages":[]}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid-send-date":{"summary":"Invalid sendDate format","description":"invalid-send-date","value":{"error":{"code":4,"message":"Invalid sendDate format. Expected ISO 8601 (e.g. 2026-12-31T23:59:59Z)."}}},"count-out-of-range":{"summary":"count out of range","description":"count-out-of-range","value":{"error":{"code":5,"message":"Parameter \u0027count\u0027 must be between 1 and 100."}}}}}}},"401":{"description":"Unauthorized. Empty or missing api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":2,"message":"Empty or missing api-key"}}}}},"403":{"description":"Forbidden. Invalid path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":3,"message":"Invalid path"}}}}},"500":{"description":"Internal server error"}}}},"/messagestatus/{messageid}":{"get":{"tags":["MessageStatus"],"summary":"Get SMS details from message ID","description":"Retrieves the delivery status for a specific message.","operationId":"getSmsDetailFromMessageId","parameters":[{"name":"messageid","in":"path","description":"Message ID to query","required":true,"schema":{"type":"string","format":"uuid","example":"54149766-7f65-4d02-b29d-406a42ca7a88"}}],"responses":{"200":{"description":"Message status details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageStatusWrapper"},"examples":{"found":{"summary":"Message found","description":"found","value":{"message":{"id":"30307af0-6d8b-4fbf-b4f3-b0e1fc32381c","reference":{"service":"DIGITALSIGN","action":"TEST","key":"apistatus-live-test-001"},"channel":"SMS","status":"DELIVERED","providerAcceptanceAt":"2026-02-27T09:06:58Z","statusChangedAt":"2026-02-27T09:07:08Z","provider":{"name":"PROVIDER1","id":"1565fbb5-3d73-4da4-96d2-e91d987f23b4","status":"DELIVERED","code":"0"},"sms":{"segments":1}}}},"foundWithoutReference":{"summary":"Message found, no reference specified in send request","description":"foundWithoutReference","value":{"message":{"id":"e989c2ec-c476-4224-a2b4-f21c76b551bb","reference":{},"channel":"SMS","status":"DELIVERED","providerAcceptanceAt":"2026-02-26T21:47:22Z","statusChangedAt":"2026-02-26T21:47:30Z","provider":{"name":"PROVIDER2","id":"381b43c9-fff3-4f5e-b35c-1cf387f2d49f","status":"DELIVERED","code":"0"},"sms":{"segments":1}}}}}}}},"400":{"description":"Bad request"},"401":{"description":"Unauthorized. Empty or missing api-key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":2,"message":"Empty or missing api-key"}}}}},"403":{"description":"Forbidden. Invalid path.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":3,"message":"Invalid path"}}}}},"404":{"description":"Message not found. No message exists with the specified ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":{"code":1,"message":"Message not found"}}}}},"500":{"description":"Internal server error"}}}}},"components":{"schemas":{"MessageStatus":{"required":["id","providerAcceptanceAt","statusChangedAt"],"type":"object","properties":{"id":{"type":"string","description":"Message identifier","format":"uuid","example":"54149766-7f65-4d02-b29d-406a42ca7a88"},"reference":{"$ref":"#/components/schemas/ReferenceService"},"channel":{"type":"string","description":"Delivery channel.","enum":["SMS","RCS"]},"status":{"type":"string","description":"Current delivery status.","enum":["SENT","DELIVERED","REJECTED","UNDELIVERED","READ","PROVIDER_ACCEPTANCE"]},"providerAcceptanceAt":{"type":"string","description":"Timestamp when the message was accepted by the provider (ISO 8601 format, e.g., 2026-02-12T14:51:00Z). Corresponds to the initial PROVIDER_ACCEPTANCE status.","format":"date-time"},"statusChangedAt":{"type":"string","description":"Timestamp of the most recent status change (ISO 8601 format, e.g., 2026-02-12T14:51:05Z).","format":"date-time"},"provider":{"$ref":"#/components/schemas/MessageStatusProvider"},"sms":{"$ref":"#/components/schemas/SmsInfo"}},"description":"SMS message status"},"MessageStatusProvider":{"type":"object","properties":{"name":{"type":"string","description":"Provider name."},"id":{"type":"string","description":"Provider\u0027s message identifier."},"status":{"type":"string","description":"Provider-specific status."},"code":{"type":"string","description":"Provider status/error code."},"message":{"type":"string","description":"Optional provider error details (e.g. `Number Blocked by Carrier`)."}},"description":"SMS provider details"},"MessageStatusWrapper":{"type":"object","properties":{"message":{"$ref":"#/components/schemas/MessageStatus"}},"description":"Single message wrapper"},"ReferenceService":{"type":"object","properties":{"service":{"maxLength":50,"type":"string","description":"Service identifier (e.g., AUTHENTICATION, ECOMMERCE, DIGITALSIGN)."},"action":{"maxLength":50,"type":"string","description":"Action within the service (e.g., 2FA, PASSWORD_RESET)."},"key":{"maxLength":255,"type":"string","description":"Custom tracking key (e.g., user ID, order ID).","example":"ref-12345"}},"description":"Tracking reference to correlate SMS with your business logic. May be an empty object (`{}`) if no reference was specified in the send request."},"SmsInfo":{"type":"object","properties":{"segments":{"type":"integer","description":"Number of SMS segments used. Messages exceeding 160 characters (GSM-7) or 70 characters (UCS-2) are split into multiple segments.","format":"int32"}},"description":"SMS info"},"SmsStatisticsResponse":{"type":"object","properties":{"messages":{"type":"array","description":"List of SMS message statuses.","items":{"$ref":"#/components/schemas/MessageStatusWrapper"}}},"description":"List of message statuses"},"ErrorDetail":{"type":"object","properties":{"code":{"type":"integer","description":"Machine-readable error code.","format":"int32","enum":[1,2,3,4,5],"x-enum-descriptions":{"1":"Message not found","2":"Empty or missing api-key","3":"Invalid path","4":"Invalid send date","5":"Invalid count parameter"}},"message":{"type":"string","description":"Human-readable error message."}},"description":"Error detail"},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}},"description":"Error response wrapper"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"HTTP API Key authentication using account credentials.\n\n**Format**: `X-Api-Key: YOUR_API_KEY`\n\n**How to obtain credentials**:\n1. Contact Namirial support to create a Message Status API account\n2. Receive API key via secure channel\n3. Test credentials in TEST environment first\n\nSee [Authentication documentation](https://docs.namirial.app/products/sms/enterprise-documentation/developer-documentation/authentication-api-status) for details.","name":"X-Api-Key","in":"header"}}}}