NimbaSMS

create_contact

• ⚠Without 'groups', the contact is added to the account's default contact list. Specifying a non-existent group returns a 400 error — use list_groups to retrieve valid names.
• ⚠The 'numero' field must include the country code without the '+' (e.g. 224XXXXXXXXX), unlike send_verification, which expects E.164 format with '+'. An incorrect format returns a 400 error.
• ⚠Creating a contact with an already existing number may return a duplicate error — check with list_contacts before bulk inserting.

get_balance

• ⚠The 'balance' field is DEPRECATED — use 'sms_balance' for the SMS balance. Both are returned but 'balance' will be removed in a future version.
• ⚠sms_balance is in number of SMS (units), not in GNF. A balance of 100 means 100 SMS available.
• ⚠Check the balance before any bulk send — an insufficient balance returns a 400 error with the 'solde' field in send_message's error response.

get_message

• ⚠The identifier field in the response is 'messageid' (not 'id'). Use the messageid returned by send_message.
• ⚠sent_at is a Unix timestamp in seconds (integer), not an ISO 8601 date. Convert with new Date(sent_at * 1000) in JavaScript.
• ⚠The overall status ('status') can be 'sent' while some recipients in 'numbers' have status 'failure' or 'not_available'. Inspect 'numbers' for the per-recipient status.
• ⚠The 'received' status in 'numbers' means delivered (delivery receipt received from the carrier). 'sent' means sent to the carrier but not yet confirmed delivered.

list_contacts

• ⚠The response is paginated. Use 'limit' and 'offset' to navigate between pages — the 'next' field contains the full URL of the next page.
• ⚠The NimbaSMS SDK strips the 'count', 'next', 'previous' fields from the response and returns only 'results'. When calling the API directly, the raw response contains all of these fields.

list_groups

• ⚠The group names returned here are the ones to pass to create_contact({ groups: [...] }). Case is significant — copy the exact values returned by this endpoint.
• ⚠Groups cannot be created via the API — they must be created from the NimbaSMS dashboard.
• ⚠The NimbaSMS SDK strips the 'count', 'next', 'previous' fields from the paginated response and returns only 'results'. When calling the API directly, the raw response contains all of these fields.

list_messages

• ⚠The response is paginated — the 'count' field gives the total but 'results' contains only the current page. Use 'next' to iterate over all pages.
• ⚠The sent_at__lte and sent_at__gte filters can be combined to define a date range. The accepted date format is not documented — see open_questions.
• ⚠Each item returned in 'results' includes a message_cost field indicating the number of SMS consumed for that message (length × recipients). Use this field for consumption reports.

list_sendernames

• ⚠Only sender names with status 'accepted' can be used in send_message and send_verification. Valid statuses are 'pending' (under validation), 'refused' (refused) and 'accepted' (usable) — not 'active'.
• ⚠Sender names are approved manually by NimbaSMS — they cannot be created via the API. Create them from the dashboard, then retrieve them here.
• ⚠The value returned in 'name' must be used as is in send_message({ sender_name: '...' }) — it is case-sensitive.
• ⚠The NimbaSMS SDK strips the 'count', 'next', 'previous' fields from the paginated response and returns only 'results'. When calling the API directly, the raw response contains all of these fields.

send_message

• ⚠sender_name is case-sensitive and must exactly match a name with status 'accepted' returned by list_sendernames. 'active' is not a valid status — it is 'accepted'.
• ⚠The 'to' field accepts three interchangeable formats: local (623XXXXXX), with country code (224623XXXXXX), or E.164 (+224623XXXXXX). Maximum 30 recipients per request.
• ⚠The message is limited to 665 characters (5 SMS). Beyond 160 characters, message_cost increases proportionally. Use the simulator to estimate before sending.
• ⚠The HTTP response is 201 Created (not 200). The response contains only messageid, message_cost and url — the full details (per-recipient status) are in GET /v1/messages/{messageid}.
• ⚠400 errors return fields with string values (not arrays): sender_name, solde, to, detail. Check the balance with get_balance before a bulk send.

send_verification

• ⚠sender_name is REQUIRED (not optional) and case-sensitive. Use list_sendernames to retrieve the names with status 'accepted'.
• ⚠The <1234> placeholder in 'message' is required — without it, the code will not be included in the SMS. The text around the placeholder is free-form.
• ⚠The identifier field in the response is 'verificationid' (not 'id'). Store this field server-side to call verify_code.
• ⚠expiry_time and attempts are sent as null when not provided — the API applies its own internal defaults.
• ⚠The generated code is returned in the API response ('code' field) — never expose it client-side; use it only for testing.
• ⚠For WhatsApp (channel: 'whatsapp'), the message content is replaced according to a NimbaSMS template — the 'message' field is ignored.

verify_code

• ⚠The 'code' field is an integer (not a string). Send the code entered by the user as an integer in the JSON body.
• ⚠The 'id' field in the URL corresponds to the 'verificationid' field (not 'id') returned by send_verification.
• ⚠The 'too_many_attemps' status (with a single letter 't' in 'attempts') is a typo in the NimbaSMS API — handle this exact value in the code.
• ⚠Each wrong call decrements the attempt counter. Once exhausted (status: 'too_many_attemps'), the verification expires — create a new one via send_verification.
• ⚠Never call this endpoint client-side — call it only server-side with the code entered by the user. An 'approved' status must immediately mark the number as verified in the database.
• ⚠A 200 response is not an approval: decide on status === "approved" (docs: "approved : Demande de verification approuvée"). Any other status (pending, expired, too_many_attemps…) means the number is not verified.

webhook_sms_status

• ⚠Your server must return HTTP 200 immediately upon receipt — NimbaSMS resends the notification up to 3 times if the response is not 200. Any heavy processing must be asynchronous.
• ⚠The webhook is configured in the NimbaSMS dashboard (API KEYS > Webhooks), not via the API. Only one webhook URL per account.
• ⚠Notifications are only available for messages sent via the API (metadata.message_type: 'API').
• ⚠NimbaSMS does not sign incoming requests — validate that messageid actually exists in your system before processing the notification, to guard against fraudulent requests.
• ⚠The webhook receives one event per recipient ('contact' field) — a message sent to 10 recipients can trigger up to 10 separate webhook calls.