NAV
cURL Swift 3.0

Overview

Welcome to the SimpleVisa API! You can use our API to access SimpleVisa API endpoints.

To get started using the SimpleVisa API:

What can the API do?

You can use the SimpleVisa API to create travel authorizations for supported destinations.

Here is the flow of events that developers most commonly follow when using our API:

Requests

The base URL for all requests to the SimpleVisa API is:

https://api.simplevisa.com/v1

Our API is REST-based. This means:

POST data should be encoded as standard application/x-www-form-urlencoded.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "https://api.simplevisa.com/v1"
  -H "x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55"
let client = SimpleVisaClient()
let simplevisa = client.authorize("bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55")

Make sure to replace the demo key with your API key.

The SimpleVisa API requires authentication by API key. You can register a new SimpleVisa API key at our developer portal.

The actual header that is used will be a base64-encoded string like this:

x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55

Most of the endpoints provided in the SimpleVisa API are in relation to a specific project. You’ll need to provide your project id and include it in the URL.

Endpoints

Get supported programs

To check supported programs, use this code:

curl -X "GET" "https://api.simplevisa.com/v1/programs"
  -H "x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55"
let client = SimpleVisaClient()
let simplevisa = client.authorize("bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55")

let programs = simplevisa.getPrograms()

The above command returns JSON structured like this:

[
  {
    "name": "eVisa",
    "alias": "atg-evisa",
    "country": "Antigua and Barbuda"
  },
  {
    "name": "ETA",
    "alias": "aus-eta",
    "country": "Australia"
  },
  {
    "name": "eVisitors",
    "alias": "aus-evisitors",
    "country": "Australia"
  }
]

Get all supported travel authorization programs supported by SimpleVisa. One country can have multiple programs available depending on preference or traveler’s nationality. They can also be of different type: Visa Waivers, Electronic Visas, Visas on Arrival, etc.

HTTP Request

GET /programs

Get a quote

curl -X "POST" "https://api.simplevisa.com/v1/quotes" \
    -H "x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "destination=USA" \
    --data-urlencode "citizenships=FRA,DEU"

extension UIViewController: SVQuoteDelegate {

let client = SimpleVisaClient()
let simplevisa = client.authorize("bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55")

simplevisa.delegate = self

let destinationCountry = "USA"
let citizenshipCountries = ["FRA","DEU"]

var quote: SVQuote?
simplevisa.createQuote(to: destinationCountry, forCitizenships: citizenshipCountry)

// createQuote delegate method
func createQuote(didSucceedCreating quote: SVQuote) {
          self.quote = quote
          //update your view
}

}

The above command returns JSON structured like this:

[
  {
    "id": "aqt_qUdje83jhdk",
    "created": "2014-04-13T10:04:03Z",
    "expires": "2014-04-13T10:09:03Z",
    "program": "usa-vwp",
    "citizenship": "FRA",
    "destination": "USA",
    "fee": 1400,
    "currency": "usd",
    "credits": 14,
    "processing_eta": "2014-04-13T10:12:03Z",
    "duration": 3
  },
  {
    "id": "aqt_qUdje83hfyt",
    "created": "2014-04-13T10:04:03Z",
    "expires": "2014-04-13T10:09:03Z",
    "program": "usa-vwp",
    "citizenship": "DEU",
    "destination": "USA",
    "fee": 1400,
    "currency": "usd",
    "credits": 14,
    "processing_eta": "2014-04-13T10:12:03Z",
    "duration": 3
  }
]

//will return a Quote object

HTTP Request

POST /quotes

Query Parameters

Parameter Description
destination The ISO 3166-1 alpha-3 code of the traveler’s destination country.
citizenships An array of the ISO 3166-1 alpha-3 code of the traveler’s citizenships.

Get eligibility

To get a specific program’s details , use this code:

curl -X "GET" "https://api.simplevisa.com/programs/:program_id?citizenship=FRA" \
    -H "x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55"
let client = SimpleVisaClient()

let simplevisa = client.authorize("bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55")

let programId = Program.usa-vwp
let citizenshipCountry = "FRA"

simplevisa.getEligibility(for: programId, with: citizenshipCountry)

The above command returns JSON structured like this:

{
    "citizenship":"FRA",
    "destination":"USA",
    "program_code":"usa-vwp",
    "eligible": true,
    "cost": 14.00,
    "currency_code": "USD",
    "validity":1800,
    "entries":-1,
    "max_stay":180,
    "starting_date":"date_of_entry",
    "credits": 14,
    "processing_eta": "2014-04-13T10:12:03Z",
    "duration": 3,
    "payload": { }
}

Get a program’s detail to know what’s supported (creation, retrieval, check) for each program, and to know what payload (payload) to send when preparing an application.

HTTP Request

GET /programs/:program_id?citizenship=:citizenship

Query Parameters

Parameter Description
citizenship The ISO 3166-1 alpha-3 code of the traveler’s main citizenship.

List applications

you can list all your applications by using this code:

curl -X "GET" "https://api.simplevisa.com/v1/applications" \
    -H "x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55"

This will result in a response structured like this:

{
    "code": 200,
    "success": true,
    "status": "ok",
    "messages": [],
    "result": [
        {
          "id": 123,
          "number": "XS76H9JJJD92JN2L",
          "complete": true,
          "status": "Authorization Approved",
          "expires": "2017-08-26"
        },
        {

        }
      ]
}

List all applications for a customer.

pagination

HTTP Request

GET /applications

Prepare an application

HTTP Request

POST /applications

Query Parameters

Parameter Description
quote_id The ID of a previously generated delivery quote. Optional, but recommended. Example: “aqt_KSsT9zJdfV3P9k”
payload A detailed payload of the application to be processed. See program details.
payload_reference Optional reference that identifies the manifest. Example: “Customer #690”

Import an application

Import an application like this:

curl -X "POST" "https://api.simplevisa.com/v1/applications/import" \
    -H "x-api-key: bkayZOMvuy8aZOhIgxq94K9Oe7Y70Hw55" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "program_id=usa-vwp"
    --data-urlencode "payload={\"data\"=\"data\"}" \

This will give you the result like this, or an error if the application was not found.

{
    "code": 201,
    "status": "created",
    "success": true,
    "messages": [],
    "result": []
}

It is possible to import existing applications into your account, if the country’s program allows it (see program’s details to check ). This endpoint allows you to check for an existing travel authorization or retrieve a lost one on the country’s program system.

HTTP Request

POST /applications/import

Query Parameters

Parameter Description
program_id The program Id of the application to import
payload The payload to import a document based on the program’s details

Get an application

Retrieve updated details about an application.

HTTP Request

GET /applications/:application_id

Errors

Error responses include details about what went wrong.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/vnd.api+json

{
  "errors": [
    {
      "status": "400",
      "source": { "pointer": "/data/attributes/first-name" },
      "title": "Invalid Attribute",
      "detail": "First name must contain at least three characters."
    },
    {
      "status": "400",
      "source": { "pointer": "/data/attributes/first-name" },
      "title": "Invalid Attribute",
      "detail": "First name must contain an emoji."
    }
  ]
}

Error responses include details about what went wrong.

Error Codes

This list will likely become more comprehensive as features are implemented.

invalid_params - The indicated parameters were missing or invalid.
unknown_destination - We weren’t able to understand the provided destination, or we don’t support it yet. This usually indicates the destination code is wrong, or perhaps not exact enough.
request_rate_limit_exceeded - This API key has made too many requests.
account_suspended
not_found
service_unavailable
application_limit_exceeded - You have hit the maximum amount of ongoing applications allowed.
customer_limited - Your account’s limits have been exceeded.
agents_busy - All of our agents are currently busy.

Resources

Approval Guidelines

Once you’ve registered for a developer account, you’ll be put into a queue to be considered for a production API key. Below you’ll find some guidelines for getting approved.

Here are some good use cases for the API:

You will most likely not be approved for a production key in these scenarios: