Sinch Getting Started: Account Setup & First API Call

Getting started overview

Integrating with Sinch APIs allows developers to add communication capabilities like SMS, voice, and verification to their applications. This guide provides a structured approach to getting started, covering account creation, credential retrieval, and executing a foundational API request. The process is designed to ensure a quick initial setup for developers aiming to leverage Sinch's communication platform.

The primary steps involve:

1. Signing up for a Sinch developer account.
2. Locating and understanding your API credentials.
3. Sending a test message using the Sinch SMS API.

Sinch provides comprehensive documentation and SDKs in multiple languages, including Java, Node.js, Python, Ruby, PHP, and .NET, to streamline the integration process. This guide focuses on a direct API call using cURL for broad applicability, though equivalent steps apply to SDK usage.

Quick Reference Guide

Create an account and get keys

Before making any API requests, you must create a Sinch developer account and obtain your API credentials. Sinch offers a free tier with credits to get started, allowing developers to test functionality without immediate financial commitment.

Account Creation Process

1. Navigate to the Sinch Website: Go to the Sinch homepage.
2. Sign Up: Look for a "Get Started" or "Sign Up" button, typically found in the top right corner or prominently displayed on the page.
3. Complete Registration: Follow the prompts to enter your email, create a password, and provide any required personal or company details. You may need to verify your email address.
4. Access the Dashboard: Once registered and logged in, you will be directed to the Sinch developer dashboard.

Retrieving API Credentials

Sinch uses a combination of a Service Plan ID and an API Token for authentication with many of its services, especially the SMS API. These credentials uniquely identify your application and authorize your requests.

1. Locate SMS API Section: From your Sinch dashboard, navigate to the SMS section. This is usually accessible via a left-hand navigation menu.
2. Select Your Service Plan: Within the SMS section, you will typically find an option for "API" or "Service Plans." If you haven't created one, Sinch may prompt you to create a default SMS service plan.
3. Reveal Credentials: On the Service Plan details page, you will find your Service Plan ID and an option to reveal or generate your API Token. The API Token is sensitive and should be treated like a password.
4. Record Credentials: Copy both the Service Plan ID and the API Token. Store them securely, ideally using environment variables or a secrets management service in production environments, as recommended by security best practices for API key management.

For certain advanced features or other Sinch APIs (e.g., Voice API), you might use different authentication methods, such as an Application Key and Secret, or OAuth 2.0. Always refer to the specific API reference documentation for the authentication method required by the endpoint you are targeting.

Your first request

This section demonstrates how to send your first SMS using the Sinch SMS API. We'll use cURL for simplicity, which is available on most systems and allows direct interaction with the API endpoints.

Prerequisites

• A Sinch developer account with SMS service enabled.
• Your Service Plan ID and API Token.
• A provisioned Sinch phone number (optional, but recommended for outbound messaging unless using an alphanumeric sender ID). If you don't have one, you can purchase a virtual number via your Sinch dashboard.
• A mobile phone number to send the test SMS to.

Sending an SMS via cURL

The Sinch SMS API endpoint for sending messages is https://us.sms.api.sinch.com/xms/v1/{servicePlanId}/batches. Replace {servicePlanId} with your actual Service Plan ID.

Construct a cURL command similar to the following. Remember to replace placeholder values with your actual credentials and numbers:

curl -X POST \
  https://us.sms.api.sinch.com/xms/v1/YOUR_SERVICE_PLAN_ID/batches \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -d '{ 
    "from": "+12025550100", 
    "to": ["+12025550101"], 
    "body": "Hello from Sinch! This is my first SMS API call."
  }'

Explanation of the cURL command:

• -X POST: Specifies the HTTP method as POST.
• https://us.sms.api.sinch.com/xms/v1/YOUR_SERVICE_PLAN_ID/batches: The API endpoint URL, customized with your Service Plan ID.
• -H 'Content-Type: application/json': Sets the request header to indicate that the body is in JSON format.
• -H 'Authorization: Bearer YOUR_API_TOKEN': Authenticates your request using your API Token as a Bearer token.
• -d '{ ... }': Contains the JSON payload for the message.
  • "from": "+12025550100": The sender's phone number (your Sinch virtual number) or an alphanumeric sender ID.
  • "to": ["+12025550101"]: An array of recipient phone numbers.
  • "body": "Hello from Sinch! This is my first SMS API call.": The content of your SMS message.

Expected Response

A successful request will typically return an HTTP 201 Created status code and a JSON response similar to this, indicating the message batch was accepted for processing:

{
  "id": "019c0631-7e87-4384-933e-00a8a6198f7e",
  "to": [
    "+12025550101"
  ],
  "from": "+12025550100",
  "body": "Hello from Sinch! This is my first SMS API call.",
  "status": "QUEUED",
  "created_at": "2026-05-29T10:30:00Z",
  "modified_at": "2026-05-29T10:30:00Z"
}

The id field is a unique identifier for your message batch, which can be used to track delivery status (e.g., via webhooks or the Get Batch Status API).

Common next steps

After successfully sending your first message, consider these common next steps to further integrate Sinch into your application:

• Implement Webhooks: Configure webhooks to receive delivery reports and incoming messages in real-time. This is crucial for tracking message delivery status and handling replies.
• Explore Other APIs: Investigate other Sinch APIs, such as the Voice API for programmatic calls, the Verify API for two-factor authentication, or the Conversations API for omnichannel messaging.
• Use an SDK: Integrate one of Sinch's official SDKs (Java, Node.js, Python, Ruby, PHP, .NET) to simplify API interactions and manage authentication within your preferred programming language. The Sinch reference documentation provides details for each SDK.
• Error Handling: Implement robust error handling in your application to manage API responses, network issues, and potential rate limits. Refer to the Sinch API error handling guide.
• Scalability and Security: As your application grows, consider strategies for managing API keys securely and optimizing your API calls for performance and scalability. For example, using a secrets manager for API keys is a strong security practice, as outlined in guides like the AWS Secrets Manager documentation.
• Monitor Usage: Regularly review your API usage and billing information within the Sinch dashboard to track costs and ensure efficient resource utilization.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

• Check Credentials: Double-check that your Service Plan ID and API Token are correct and have been placed accurately in the cURL command. Typos are a frequent cause of authentication errors.
• Authorization Header Format: Ensure the Authorization header is correctly formatted as Bearer YOUR_API_TOKEN.
• JSON Payload Syntax: Verify that your JSON request body is valid. Tools like online JSON validators can help identify syntax errors.
• Phone Number Format: Ensure both the from and to phone numbers are in E.164 format (e.g., +12025550101), including the country code.
• Sinch Number Provisioning: If you are sending from a Sinch number, confirm that the number is provisioned to your account and associated with the correct service plan.
• Account Balance/Credits: Check your Sinch account balance or free credits. Insufficient funds can prevent messages from being sent.
• API Endpoint Region: Confirm that you are using the correct regional API endpoint (e.g., us.sms.api.sinch.com for the US). Sinch supports multiple regions, and using the wrong one can lead to connection issues.
• Firewall/Network Restrictions: If you are making requests from a restricted network, ensure that outbound connections to Sinch's API endpoints are not blocked by a firewall.
• Review API Error Messages: The API response often contains specific error messages that can guide your troubleshooting. For example, a 401 Unauthorized typically points to credential issues, while a 400 Bad Request suggests problems with the request body or parameters. Consult the Sinch error codes documentation for detailed explanations.
• Sinch Dashboard Logs: Check the message logs within your Sinch dashboard. These logs can provide server-side insights into why a message failed, including specific error codes and descriptions from the Sinch platform.