Request format

The TextMe API accepts the same document in two encodings. Send XML with Content-Type: application/xml, or the equivalent JSON with Content-Type: application/json, and the reply comes back in whichever you sent.

Nothing else changes between the two: the same field names, the same nesting, the same status codes. Every example on this site shows both.

The envelope

A request is a single root element that names the operation, containing a user block and the operation's own fields.

XML

<?xml version="1.0" encoding="UTF-8"?>
<sms>
    <user>
        <username>Leeroy</username>
    </user>
    <source>DemoAPI</source>
    <destinations>
        <phone>5xxxxxxxx</phone>
    </destinations>
    <message>Hello</message>
</sms>

JSON

{
  "sms": {
    "user": { "username": "Leeroy" },
    "source": "DemoAPI",
    "destinations": { "phone": "5xxxxxxxx" },
    "message": "Hello"
  }
}

The root element is the operation selector: sms, bulk, dlr, newCL, blacklist, and so on. Sending an unrecognised root returns status 997, Not a valid command sent.

Repeated elements become arrays

XML repeats an element to express a list. JSON expresses the same list as an array — and, where only one item is present, the API also accepts the bare value.

XML

<destinations>
    <phone>5xxxxxxx1</phone>
    <phone>5xxxxxxx2</phone>
</destinations>

JSON

{
  "destinations": {
    "phone": ["5xxxxxxx1", "5xxxxxxx2"]
  }
}

Attributes become $, text becomes _

Some XML elements carry attributes — the id on a <phone>, the id on a <link>. JSON has no attributes, so the API uses a convention borrowed from XML-to-JSON converters: $ holds the attributes, _ holds the element's text.

XML

<destinations>
    <phone id="order-10052">5xxxxxxxx</phone>
    <phone>5xxxxxxxx</phone>
</destinations>

JSON

{
  "destinations": {
    "phone": [
      { "$": { "id": "order-10052" }, "_": "5xxxxxxxx" },
      { "_": "5xxxxxxxx" }
    ]
  }
}

An element with no attributes can stay a plain string, as in the first example on this page. The convention only appears where XML would have used an attribute — which in practice is the id on phone and on link.

Which encoding should you pick?

XML is the API's native shape and the vendor's own examples use it. JSON is easier to build and parse in most modern stacks, and is what the client examples on this site use. Neither is deprecated; choose whichever your code handles more naturally.

Response envelope

Every response opens with the same two fields.

Field	Type	Meaning
status	int	0 on success. Anything else is an error.
message	string	A human-readable note. On success it describes what happened (SMS will be sent); on failure it explains the error.

Operation-specific data follows: shipment_id after a send, transactions in a report, contact_lists in a list read, and so on.

XML

<?xml version="1.0" encoding="UTF-8"?>
<sms>
    <status>0</status>
    <message>SMS will be sent</message>
    <shipment_id>xxxxxxx</shipment_id>
</sms>

JSON

{
  "status": 0,
  "message": "SMS will be sent",
  "shipment_id": "XXXXXXX"
}

Some operations also return an errors list alongside a successful status: the request as a whole worked, but individual items inside it did not. Creating a contact list with one malformed phone number is the usual case — the list is created, and the bad row is reported. Always read errors when it is present.

status is not the HTTP status

The transport almost always answers HTTP 200, including for authentication failures and validation errors. Branch on the status field in the body, never on the HTTP code alone.

Values and formats

Field kind	Format	Notes
Phone number	5xxxxxxxx or 05xxxxxxx	Landlines follow the same shape (3xxxxxxx). Numbers that are too short or too long are rejected with status 9.
Date and time	dd/mm/yy hh:mm	30/03/26 10:10. Two-digit year, 24-hour clock.
Sender	up to 11 chars	Letters and digits only, no +. Must be verified or the call fails with status 515.
Message body	up to 1005 chars	Longer or empty bodies return status 989.
Campaign name	up to 50 chars	Also returns status 989 when too long.
Flags	1 or 0	Sent as strings. Any value other than the documented one is read as "no".

Hebrew, emoji and other non-Latin text are fine — the whole API is UTF-8. Bear in mind that non-GSM characters shorten how much fits in a single billed message segment.

Testing without sending

POST https://my.textme.co.il/api/test

The test endpoint parses and validates the payload, applies the same permission and format checks, and answers in the same shape — but performs no action. Nothing is sent, no credit is spent, no list is touched.

It is the right place to confirm that a payload is well-formed before pointing the same code at /api. It does not tell you whether a number is reachable, and it does not create a shipment_id you can later report on.

What can go wrong

Status	Meaning
1	The XML could not be parsed — malformed document, unclosed tag, or a body that is not XML at all.
2	A required field is missing. The message names it.
997	The root element is not a recognised operation.
998	Unknown error in the request.

The full list, including operation-specific codes, is in Status codes.