Tavoittaja API documentation

Changelog

2025-09-30 Initial release
2025-11-07 Added SMS delivery report documentation
2025-11-24 Added with Tracking endpoint

Authentication

You can create the Tavoittaja API -authentication key on Tavoittaja account → API. When creating the API key, it is also possible to provide an email address to receive updates on API changes. You are allowed to create multiple API-keys for your account.

Always store your generated API -keys safely! Do not allow public access to your API keys.

Requests

Tavoittaja API uses HTTP requests, which are handled in JSON format.

Endpoint format is https://api2.tavoittaja.fi/api/<resourceName>. Please note that http is not supported. SSL is required with TLS 1.2+ support.

Error response format

Errors are returned with non-200 HTTP codes. All success responses are 200 others are considered errors.

{
    "errors": [
        {
            "code": 400,
            "title": "Error",
            "details": "Invalid phone number provided."
        }
    ]
}

Headers

All Tavoittaja API endpoints require headers to be used. Add your API key to Authorization header.

Authorization: upcqg15aygerfvs933n1gbajjjp34kju1c7dr72uqwe1d6duxecfee1hyi50bkyj

Sender names

You need to have you sender name authorized on Tavoittaja to send SMS to Finland. Log in → Account → Sender names → Add sender name. Currently if you haven’t authorized your sender name SMS gets sent with sender name “Tuntematon” in Finland. Later in 2026 SMS with unauthorized names will be blocked completely.

In Finland Traficom has a list of protected sender names. These sender names are blocked on Tavoittaja. If you want to use one of these sender names email to us at support@prospectum.fi

https://www.traficom.fi/fi/viestinta/laajakaista-ja-puhelin/sms-sender-id-tunnus

Tavoittaja contacts

If your Tavoittaja account has contacts we will also link SMS messages to these contacts using phone number. This way you see all SMS sent to contact on Tavoittaja UI.

Phone numbers

Recommended format for phone numbers is E.164 the international format with country code (+358). If other formats are used we will try to convert the phone number to a valid Finnish phone number by adding +358.

Credits

Credits are charged on your account for each successful recipient. If recipient is rejected you won’t be charged for it.

Endpoints

Send SMS

This is recommended way of sending SMS. You may send multiple messages in a single request and / or send the same message to multiple recipients. We are not enforcing any strict limit on how many messages or recipients you may send in each request.

URL

https://api2.tavoittaja.fi/api/sms/send/multiple

HTTP method

POST

Headers

Authorization: {YOUR_TAVOITTAJA_API_KEY}

Parameters

messages (array of objects)
Each object inside the array have following properties:

Parameter	Type	Description	Required
sender	string(max:16)	Phone number to be used as a sender in international E.164 format (+358) or alphanumeric sender name (max length 11 characters)	Yes
receiverPhones	array of strings	Receiver phone numbers in international E.164 format.	Yes
content	string(max: 918)	SMS message content.	Yes

Examples

POST data

{
    "messages": [
        {
            "sender": "PostTest",
            "content": "Test message 1.",
            "receiverPhones": [
                "+35844123123",
                "+358111111"
            ]
        },
        {
            "sender": "PostTest2",
            "content": "Test message 2.",
            "receiverPhones": [
                "+358449876543"
            ]
        }
    ]
}

Response (HTTP 200)

Recipients with valid phone numbers are added to acceptedRecipients array of objects. Recipients with invalid phone numbers are rejected and added to rejectedRecipients array of strings. No credits will be charged for recipients that are rejected.

{
    "messages": [
        {
            "sender": "PostTest",
            "content": "Test message 1.",
            "acceptedRecipients": [
                {
                    "smsMessageRecipientID": 101,
                    "phone": "+35844123123",
                    "contentCharacterCount": 15,
                    "segmentCount": 1,
                    "creditCount": 1
                }
            ],
            "rejectedRecipients": [
                "+358111111"
            ],
            "smsMessageID": 35
        },
        {
            "sender": "PostTest2",
            "content": "Test message 2.",
            "acceptedRecipients": [
                {
                    "smsMessageRecipientID": 102,
                    "phone": "+358449876543",
                    "contentCharacterCount": 15,
                    "segmentCount": 1,
                    "creditCount": 1
                }
            ],
            "rejectedRecipients": [],
            "smsMessageID": 36
        }
    ]
}

Send SMS with tracking

If you want to track delivery status of your messages you may use this endpoint to set deliveryStatusCallbackUrl. You may send multiple messages in a single request and / or send the same message to multiple recipients. We are not enforcing any strict limit on how many messages or recipients you may send in each request.

With tracking we are calling deliveryStatusCallbackUrl for every status change we receive from operators.

URL

https://api2.tavoittaja.fi/api/sms/send/withTracking

HTTP method

POST

Headers

Authorization: {YOUR_TAVOITTAJA_API_KEY}

Parameters

messages (array of objects)
Each object inside the array have following properties:

Parameter	Type	Description	Required
sender	string(max:16)	Phone number to be used as a sender in international E.164 format (+358) or alphanumeric sender name (max length 11 characters)	Yes
content	string(max: 918)	SMS message content.	Yes
deliveryStatusCallbackUrl	string(max: 500)	Your endpoint URL, that is called for each delivery status change. Must be a valid URL.	Yes
receivers	array of objects	Array of receiver object. See receiver structure below.	Yes

receivers (array of objects)

Parameter	Type	Description	Required
receiverPhone	string(max:16)	Receiver phone numbers in international E.164 format.	Yes
externalID	string(max:50)	Your system ID for the recipient used in tracking.	Yes

Examples

POST data

{
    "messages": [
        {
            "sender": "PostTest",
            "content": "Test message 1.",
            "deliveryStatusCallbackUrl": "https://myapi.com/tavoittajacallback",
            "receivers": [
                {
                    "receiverPhone": "+35844123123",
                    "externalID": "YOUR_EXTERNAL_ID"
                },
                {
                    "receiverPhone": "+358111111",
                    "externalID": "YOUR_EXTERNAL_ID_2"
                }
            ]
        },
        {
            "sender": "PostTest2",
            "content": "Test message 2.",
            "deliveryStatusCallbackUrl": "https://myapi.com/tavoittajacallback",
            "receivers": [
                {
                    "receiverPhone": "+358449876543",
                    "externalID": "YOUR_EXTERNAL_ID_3"
                }
            ]
        }
    ]
}

Response (HTTP 200)

Recipients with valid phone numbers are added to acceptedRecipients array of objects. Recipients with invalid phone numbers are rejected and added to rejectedRecipients array of objects. No credits will be charged for recipients that are rejected.

{
    "messages": [
        {
            "sender": "PostTest",
            "content": "Test message 1.",
            "acceptedRecipients": [
                {
                    "smsMessageRecipientID": 101,
                    "phone": "+35844123123",
                    "contentCharacterCount": 15,
                    "segmentCount": 1,
                    "creditCount": 1,
                    "externalID": "YOUR_EXTERNAL_ID"
                }
            ],
            "rejectedRecipients": [
                {
                    "receiverPhone": "+358111111",
                    "externalID": "YOUR_EXTERNAL_ID_2"
                }
            ],
            "smsMessageID": 35
        },
        {
            "sender": "PostTest2",
            "content": "Test message 2.",
            "acceptedRecipients": [
                {
                    "smsMessageRecipientID": 102,
                    "phone": "+358449876543",
                    "contentCharacterCount": 15,
                    "segmentCount": 1,
                    "creditCount": 1,
                    "externalID": "YOUR_EXTERNAL_ID_3"
                }
            ],
            "rejectedRecipients": [],
            "smsMessageID": 36
        }
    ]
}

Send a single outbound SMS message

Send a single message to a single recipient. This method exists mostly to support some older systems that aren’t capable of modifying headers or can use only GET requests.

URL

https://api2.tavoittaja.fi/api/sms/send/single

HTTP method

GET

Parameters

Url parameters

Parameter	Type	Description	Required
sender	string(max:16)	Phone number to be used as a sender in international E.164 format (+358) or alphanumeric sender name (max length 11 characters)	Yes
receiverPhone	string(max:16)	Receiver phone number in international E.164 format.	Yes
content	string(max: 918)	SMS message content.	Yes

Url encoding

Remember to encode special characters on URLs. eg. + => %2B or space => %20

Examples

GET https://api2.tavoittaja.fi/api/sms/send/single?apiKey=XXX&sender=%2B3581231231&receiverPhone=358441234567&content=Hello%20from%20Tavoittaja

Response (HTTP 200)

{
    "smsMessageRecipient": [
        {
            "smsMessageRecipientID": 111,
            "smsMessageID": 46,
            "phone": "+358441234567",
            "contentCharacterCount": 21,
            "segmentCount": 1,
            "creditCount": 1
        }
    ]
}

Delivery reports

If the deliveryStatusCallbackUrl is posted in your request data, Tavoittaja will use this url to send the delivery status report.

Delivery reports technical information

• Data is posted as JSON. Unescaped unicode characters and slashes are used.
• Request is a POST request.
• Receiving endpoint should respond with HTTP code 204 (any 2xx is accepted too) and empty response body.
• If Tavoittaja does not receive a successful HTTP response (2xx status code) from the receiving server, it will automatically retry the delivery report. The retry mechanism uses an incremental backoff strategy with a maximum of five attempts. The retry intervals are: 1, 2, 5, 10, and 60 minutes.
• Request timeout is set to 10 seconds.
• Delivery reports are not always delivered in chronological order. You may receive 1000 queued before, 1 accepted sometimes. Some operators may deliver them like this.

Examples

Success example

{
    "smsMessageRecipientID": 118,
    "externalID": "YOUR_EXTERNAL_ID"
    "statusCode": 2000,
    "statusMessage": "Billed and delivered",
    "timeDelivered": "2025-11-07 12:42:23"
}

Failed example

{
    "smsMessageRecipientID": 119,
    "externalID": "YOUR_EXTERNAL_ID"
    "statusCode": 4007,
    "statusMessage": "Not delivered",
    "timeDelivered": null
}

Explanations

Field	Description
smsMessageRecipientID	Unique ID per recipient. You can use this to identify which recipients delivery status changed.
externalID	Your system ID used to recognize recipients.
statusCode	Status code that describes current delivery status.
statusMessage	Raw operator status message in English.
timeDelivered	When message is delivered and status code is 2000. timeDelivered gets set. Otherwise null. This time is reported in UTC in ISO format. e.g. 2026-12-20 13:40:00

Status codes

Following codes are considered to be in process: 1, 2, 1000, 1001, 5000

Code 2000 is considered to be delivered successfully.

Any other code is considered error.

Status code	Description
1	Accepted
2	Scheduled
1000	Queued
1001	Sent to gateway
2000	Delivered
3000	Account validation error
3001	Configuration error
3002	Invalid sender
3003	Sender type not supported
3004	Invalid recipient
3005	Destination type not supported
3006	Encoding not supported
3007	Invalid message content
3008	Invalid user data header
3009	Maximum throttling exceeded
3010	Validation error
3011	Quota exceeded
3013	Country blocked
4000	Generic error
4001	Temporary routing error
4002	Permanent routing error
4003	Phone number blocked
4004	Recipient temporarily barred
4005	Service provider error
4006	Operation blocked
4007	Not delivered
4008	Expired
4009	Timeout
4010	Delivery report not supported
4011	Deleted by operator
5000	Retried