### SMSPortal REST API - General Guidelines Source: https://docs.smsportal.com/docs/rest/-best-practices This section details the general structure of requests to the SMSPortal REST API, including endpoints, versions, parameters, and authentication methods. ```APIDOC ## SMSPortal REST API - General Guidelines ### Request Structure All requests to the API consist of the following components: * **Endpoint:** The URL that indicates the resource being accessed. * **Version:** The version of the resource being accessed, defaulting to the latest version if not specified. * **Parameters:** Any required or optional parameters for the resource. * **Body:** Any JSON body that is required by the resource (POST requests only). * **Authorisation Parameters:** In every request made to the REST API, you are required to pass your credentials as Basic Authentication or the Token you have generated. ### Base URL The base URL for the API is `https://rest.smsportal.com` and supports HTTPS. To access a specific version of the API, append the version to the URL, e.g., `https://rest.smsportal.com/v1`. The base URL defaults to the latest API version. However, to minimize compatibility issues, always reference the specific version you are developing against in the URL. ### API Credential Security Keep your API credentials secure. Public exposure can lead to account compromise. **Do not embed API credentials directly in code**, especially in client-side applications (e.g., web apps), as they can be read by any user. ### Parameter Formatting * **Date and Time:** All date and time parameters must be in UTC and follow the ISO 8601 format. * **URL Encoding:** Parameters must be URL encoded. For readability in documentation, they may appear unencoded. * **Number Format:** Phone numbers must be in E.164 format when sending SMS internationally. ### Token Authentication vs Basic Authentication Both Token-based (AEG format) and Basic Authentication are supported on all REST endpoints. Generated tokens are valid for 24 hours and should be cached for 23 hours. API credentials are valid indefinitely until deactivated. ### Token Generation and Caching To avoid the overhead of fetching new tokens frequently, use a token cache. Tokens are valid for 24 hours and cached for 23 hours. New token requests within 23 hours will return the same token. A new token can be generated from the `/authentication` endpoint to ensure uninterrupted messaging in the last hour of a token's validity. ### Future-proofing SMSPortal ensures backward compatibility by never removing or editing existing JSON objects, properties, or error codes. However, new elements may be added at any time. Avoid assuming that only the current set of JSON objects, properties, or error codes exists. ``` -------------------------------- ### Authentication Error Codes Source: https://docs.smsportal.com/docs/rest/-error-codes Error codes specifically related to authentication and authorization issues. ```APIDOC ## Authentication Error Codes ### Description Error codes specifically related to authentication and authorization issues. ### Error Codes - **AuthenticationToken.Invalid**: The provided authentication token is invalid or missing. - **AuthenticationToken.Expired**: The provided authentication token has expired. - **InvalidCredentials**: The given credentials are invalid. - **AuthenticationHeader.Missing**: The required authentication header is missing for the request. - **AuthenticationHeader.Invalid**: The required authentication header is in an incorrect format or has an incorrect encoding. ``` -------------------------------- ### HTTP Status Codes Source: https://docs.smsportal.com/docs/rest/-error-codes Standard HTTP status codes returned by the API, indicating the general outcome of a request. ```APIDOC ## HTTP Status Codes ### Description Standard HTTP status codes returned by the API, indicating the general outcome of a request. ### Status Codes - **200 OK**: Response is correct. The body of the response will include the data requested. - **400 Bad Request**: There was an error with the request. The body of the response will have more info. - **401 Unauthorized**: Authentication or token is invalid. If your API key is wrong a 401 will be generated. Please check the API key. - **403 Forbidden**: Request contains valid data but is being refused. Typically returned if your API key or account is deactivated or has Insufficient credits. - **503 Service Unavailable**: There are multiple possible reasons for a HTTP 503 error. ``` -------------------------------- ### RESTful Error Codes Source: https://docs.smsportal.com/docs/rest/-error-codes Specific error codes related to the format, type, and existence of entities within the API. ```APIDOC ## RESTful Error Codes ### Description Specific error codes related to the format, type, and existence of entities within the API. ### Error Codes - **InvalidParameter.Format**: The provided parameter is in an invalid format. - **InvalidParameter.Type**: The provided parameter contains an invalid type. - **EntityNotFound.Group**: The provided group could not be found. - **EntityNotFound**: The requested resource could not be found. - **RequiredParameter.Missing**: A required parameter was not supplied. ``` -------------------------------- ### Sending Error Codes Source: https://docs.smsportal.com/docs/rest/-error-codes Error codes related to the process of sending messages or performing send-related operations. ```APIDOC ## Sending Error Codes ### Description Error codes related to the process of sending messages or performing send-related operations. ### Error Codes - **InsufficientCredits**: The current amount of credits is insufficient to complete the send. - **IncorrectScheduledDate**: The given end date is earlier than the start date. - **DestinationAddress.NoNetworkFound**: No network route was found for the given destination address. - **DestinationAddress.Invalid**: The given destination address is in an incorrect format. - **DestinationAddress.Optout**: The destination address has opted out of the send. - **DuplicateMessage**: A duplicate message was detected. - **EntityNotFound.ReplyRule**: The provided Reply Rule could not be found. - **EmptySend.NoValidMessages**: The provided SendRequest contained no valid messages to send. - **InternalServerError**: Unhandled error response. ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.