API Docs

Tipalink API

The Tipalink API can be used to add tipping features to websites, web applications, and mobile apps.

Give your users the ability to monetize their content on your platform by integrating with the Tipalink API.

API INTRO

This API is organized around REST.

API endpoints accept JSON-encoded request bodies and return JSON-encoded responses.

The API uses standard HTTP response codes, authentication, and verbs.

API REQUESTS

All API requests must be made securely over HTTPS.

All API POST body requests must be encoded as JSON and sent with the "Content-Type: application/json" header.

API requests must be made over HTTPS and JSON-encoded.

Authentication

A valid API key is required to access the API and a user token is required to identify and authenticate user sessions.

API Keys

The API key must be provided in an Authentication header using HTTP Basic authentication - use your API key as the username.

API keys must be kept secret and secure; do not share them publicly. Use them only in server-side requests.

DO NOT use API Keys in client-side code!

User Tokens

The user token must be provided in an Authentication header using HTTP Basic authentication - use the token as the password.

Unless otherwise noted^*, requests must include a user token.

Use HTTP Basic authentication to pass your API Key and a user token.

Example of an API request using Basic authentication:


    curl -G https://www.tipalink.com/api/v1/account \
    -u '[YOUR API KEY]:[USER TOKEN]'

* - a user token is not required for POST requests to 'api/v1/login', 'api/v1/account', and 'api/v1/profiles'; nor GET requests to 'api/v1/profiles', 'api/v1/countries', and 'api/v1/zones'.

Rate Limits

Each API key is allowed no more than 3,600 requests are per hour and 300,000 requests per month.

IP Whitelisting

You may opt-in to IP whitelisting for your API key.

API RESPONSES

All API responses are encoded as JSON and returned with the "Content-Type: application/json" header.

API responses are encoded and returned in JSON format.

All responses to invalid requests are formatted as follows:

{
    "status": [three digit HTTP Response Code, Integer],
    "error": [error message, String]
}

All responses to valid requests are formatted as follows:

{
    "status": [three digit HTTP Response Code, Integer],
    "token": [base64 encoded user token, String or Null],
    "data": [response data, Object],
    "requests": [rate limit info, Object]
    "error": [error message, String or Null]
}

All API responses to valid API requests include a user token, which is updated periodically for security purposes. Therefore, it is important to check the value of the `token` parameter returned in each API response for a potential update before sending the next request.

User Tokens are updated periodically.

All responses to valid API requests include the following rate limit information returned under the `requests` parameter for the API key supplied in the request:

{
    "used": [number of requests used this month, Integer],
    "remaining": [number of requests remaining this month, Integer],
    "resets": [date and time when counter resets in Atom format, String]
}

API ERRORS

All responses to invalid API requests include an error message that contains an HTTP status code and a description.

Excessive invalid requests^* will result in a temporary ban!

General Errors

400 - Error: Client IP Address is required! (i.e. `REMOTE_ADDR` header missing or invalid)
403 - Error: HTTPS is required!
404 - Error: Resource not found! (i.e. API endpoint does not exist)
405 - Error: Request method is not valid! (i.e. not GET or POST)
500 - Sorry, something went wrong! (i.e. request was not processed successfully by the server)
503 - Error: API is disabled!

POST Request Errors

400 - Error: Malformed JSON
400 - Error: Post body data is required!
415 - Error: Content-Type 'application/json' is required!

API Key Validation Errors

401 - Error: API key is required!
403 - Error: API key has been disabled!
403 - Error: IP is not whitelisted! (for API keys with IP whitelisting enabled)
422 - Error: API key is not valid!
429 - Error: Exceeded X requests in the last Y minutes!
429 - Error: Exceeded Z requests in the last month!

API Endpoint Errors

307 - Sorry, resource is temporarily not available!
400 - Error: Parameter is missing or not valid!
401 - Account not verified!
401 - A Profile is required!
401 - Profile has been disabled!
401 - Error: Session is required! (for API endpoints that require a user token)
403 - Login is required!
404 - Error: Not found!

* - i.e. those returing a 400-level status code

API ENDPOINTS

Select an API endpoint below to learn more.

POST api/v1/login

Logs a user in to an existing account and starts a new session.

User token is not required.

Request Body Parameters

Request body parameters `email` and `password` are both required to log in to an account.

{
    "email": [3-254 characters in valid email address format, String],
    "password": [8-50 characters and must include a lowercase letter, an uppercase letter, and a number, String]
}

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String],
    "account": [Account Object]
}

api/v1/logout

GET api/v1/logout

Logs a user out and ends their session.

User token and login is required.

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String]
}

api/v1/account

GET api/v1/account

Returns user account information.

User token and login is required.

Response Data Returned

"data": {
    "account": [Account Object] {
        "firstname": [String],
        "lastname": [String],
        "email": [String],
        "phone": [String],
        "phone_alt": [String],
        "address": [Address Object],
        "profile": [Profile Object]
    }
}

POST api/v1/account

Creates a new user account or updates an existing user account.

User token is not required to create a new account.

Request Body Parameters

Request body parameters `email` and `password` are both required to create a new account.

{
    "firstname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
    "lastname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
    "email": [3-254 valid characters in email address format, String],
    "password": [8-50 characters and must include a lowercase letter, an uppercase letter, and a number, String],
    "phone": [max 32 characters, String],
    "phone_alt": [max 32 characters, String]
}

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String],
    "account": [Account Object]^*
}

* - only provided for users who are logged in

api/v1/addresses

GET api/v1/addresses/:address_id

Returns an address associated with a user account.

User token and login is required.

Resource parameter `address_id` [Integer] is optional.

Response Data Returned

If `address_id` is supplied, then an Address Object is returned.

"data": {
    "address": [Address Object] {
        "address_id": [Integer],
        "default": [Boolean],
        "firstname": [String],
        "lastname": [String],
        "company":  [String],
        "company_id": [String],
        "address_1": [String],
        "address_2": [String],
        "city": [String],
        "postcode": [String],
        "zone": [Zone Object] {
            "zone_id": [Integer],
            "zone_name": [String],
            "zone_code": [String]
        },
        "country": [Country Object] {
            "country_id": [Integer],
            "country_name": [String],
            "country_code": [String]
        }
    }
}

If no `address_id` is supplied, then an array of Address Objects are returned.

"data": {
    "addresses": [Array of Address Objects]
}

POST api/v1/addresses/:address_id

Creates a new account address or updates an existing account address.

User token and login is required.

Resource parameter `address_id` [Integer] is optional.

Request Body Parameters

Request body parameter `address_id` [Integer] is optional.

- if `address_id` is supplied and `remove` is not, then the account address will be updated
- if `address_id` is supplied and `remove` is "true", then the account address will be deleted
- if no `address_id` is supplied, then a new account address will be created

{
    "address_id": [Integer],
    "remove": [Boolean],
    "default": [Boolean],
    "firstname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
    "lastname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
    "company":  [0-32 characters, String],
    "company_id": [0-32 characters, String],
    "address_1": [3-128 characters, String],
    "address_2": [0-128 characters, String],
    "postcode": [2-10 characters, String],
    "city": [2-128 characters, String],
    "zone_id": [Integer],
    "country_id": [Integer]
}

Response Data Returned

"data": {
    "address": [Address Object]
}

api/v1/profiles

GET api/v1/profiles/:profile_id

Returns profile information.

User token is not required.

Resource parameter `profile_id` [String] is required.

Response Data Returned

"data": {
    "profile": [Profile Object] {
        "profile_id": [String],
        "profile_name": [String],
        "profile_url": [String],
        "tagline": [String],
        "description": [String],
        "keywords": [Array of Strings],
        "image_url": [String],
        "type": [String],
        "city": [String],
        "zone": [Zone Object] {
            "zone_id": [Integer], 
            "zone_name": [String], 
            "zone_code": [String]
        },
        "country": [Country Object] {
            "country_id": [Integer], 
            "country_name": [String], 
            "country_code": [String]
        },
        "payment_methods": [Array of Strings]
    }
}

POST api/v1/profiles

Activates a new account profile or updates an existing account profile.

User token and login is required, unless creating a new profile and a new account at the same time.

Request Body Parameters

Request body parameters `name`, `city`, `zone_id`, and `country_id` are required.

Request body parameters `email` and `password` are required when creating a new profile and a new account at the same time.

See the next section for API enpoint api/v1/images for details on setting request body parameters `image_path` and `image_source_url`.

{
    "email": [3-254 valid characters in email address format, String],
    "password": [8-50 characters and must include a lowercase letter, an uppercase letter, and a number, String],
    "firstname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
    "lastname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
    "name": [2-120 characters, String],
    "alias": [2-24 characters, String],
    "tagline": [0-80 characters, String],
    "description": [0-5000 characters, String],
    "keywords": [0-5000 characters comma-separated values, String],
    "image_path": [0-128 characters, String],
    "image_source_url": [0-500 characters, String],
    "type_id": [1 for Individual or 3 for Business, Integer],
    "city": [2-128 characters, String],
    "zone_id": [Integer],
    "country_id": [Integer],
    "payment_accounts": [Object] {
        "paypal": [3-254 valid characters in email address format, String],
        "check": [address_id to be presented as mailing address, Integer]
    },
    "social_links": [Object] {
        "facebook": [0-128 characters in valid url format, String],
        "instagram": [0-128 characters in valid url format, String],
        "twitter": [0-128 characters in valid url format, String],
        "pinterest": [0-128 characters in valid url format, String],
        "youtube": [0-128 characters in valid url format, String],
        "patreon": [0-128 characters in valid url format, String],
        "linkedin": [0-128 characters in valid url format, String],
    },
    "tip_default": [Float]
}

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String],
    "profile" [Profile Object]
}

api/v1/images

POST api/v1/images

Copies an image from a specified url and saves it to an existing user account.

The `path` attribute of the `image` object in the response data can be used to update an account profile image.

User token and login is required. The user must have a profile.

Request Body Parameters

Request body parameter `image_source_url` is required and must point to the url of a file that:

- has mime type 'image/jpeg', 'image/pjpeg', 'image/x-png', or 'image/png'
- ends in '.jpg', '.jpeg', or '.png'
- has filename between 5 and 255 characters long
- is less than 8MB in size
- is at least 300px width and 300px height
- looks best when dimensions are square (1:1 ratio of width:height)

{
    "image_source_url": [0-500 characters, String]
}

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String],
    "image" [Object] {
        "source_url": [String],
        "path": [String],
        "preview_url": [String]
    }
}

api/v1/tips

GET api/v1/tips/:key

Returns a single tip or all tips of the user session.

User token is required.

Resource parameter `key` [String] is optional.

Query string parameter `limit` [Integer] is optional.

Response Data Returned

If `key` is supplied, then an Tip Object is returned:

"data": {
    "tip": [Object] {
        "key": [String],
        "link": [String],
        "link_short": [String],
        "amount": [Float],
        "amount_formatted":  [String],
        "currency": [String],
        "note": [String],
        "title": [String],
        "title_short": [String],
        "profile_id": [String],
        "max": [Float],
        "min": [Float],
        "error": [String]
    }
}

If no `key` is supplied, then Tips Object is returned:

"data": {
    "tips": [Tips Object] {
        "total": [Float],
        "total_formatted": [String],
        "currency": [String],
        "tips": [Array of Tip Objects],
        "profiles": [Object] {
            "profile_id": [String],
            "profile_name": [String],
            "profile_url": [String],
            "image_url": [String],
            "payment_methods": [Array of Strings],
            "total": [Float],
            "total_formatted": [String]
        },
        "error": [String]
    }
}

If `limit` is supplied, the amount of items returned in the `tips` array will be limited to this number.

POST api/v1/tips/:key

Adds a new tip or updates an existing tip of the user session.

User token is required.

Resource parameter `key` [String] is optional.

Request Body Parameters

Request body parameter `link` [String] is required to add a new tip.

Request body parameters `key` [String] and `note` [String] are optional.

- if `key` is supplied and `remove` is supplied as "true", then the tip will be removed
- if `key` is supplied and `amount` or `note` is supplied, then the tip will be updated

{
    "key": [Integer],
    "remove": [Boolean],
    "link": [max 128 characters in valid url format, String],
    "amount": [Float],
    "note": [0-64 characters, String]
}

It's also possible to mass update existing tips by supplying the request body parameter `tips` [Array of Objects]:

{
    "tips": [Array of Objects] [{
        "key": [String] (required),
        "amount": [Float] (required),
        "note": [0-64 characters, String]
    }]
}

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String],
    "tips": [Tips Object]
}

api/v1/countries

GET api/v1/countries/:country_id

Returns a single country or list of all countries.

User token is not required.

Resource parameter `country_id` [Integer] is optional and an ISO 3 country code [String] may be used in its place.

Response Data Returned

If `country_id` is supplied, then an Country Object is returned:

"data": {
    "country": [Country Object] {
        "country_id": [Integer],
        "country_name": [String],
        "country_code": [String]
    }
}

If no `country_id` is supplied, then an array of Country Objects are returned:

"data": {
    "countries": [Array of Country Objects]
}

GET api/v1/countries/:country_id/zones/:zone_id

Returns a list of all zones in a country or a single zone in a country.

User token is not required.

Resource parameter `country_id` [Integer] is required and an ISO 3 country code [String] may be used in its place.

Resource parameter `zone_id` [Integer] is optional a zone code [String] may be used in its place.

Response Data Returned

If `zone_id` is supplied, then a Country Object and a Zone Object is returned:

"data": {
    "country": [Country Object] {
        "country_id": [Integer],
        "country_name": [String],
        "country_code": [String]
    },
    "zone": [Zone Object] {
        "zone_id": [Integer],
        "zone_name": [String],
        "zone_code": [String]
    }
}

If no `zone_id` is supplied, a Country Object and an array of Zone Objects is returned:

"data": {
    "country": [Country Object] {
        "country_id": [Integer],
        "country_name": [String],
        "country_code": [String]
    },
    "zones": [Array of Zone Objects]
}

api/v1/zones

GET api/v1/zones/:zone_id

Returns a single zone.

User token is not required.

Resource parameter `zone_id` [Integer] is required.

Response Data Returned

"data": {
    "zone": [Zone Object] {
        "zone_id": [Integer],
        "zone_name": [String],
        "zone_code": [String]
    }
}

api/v1/currencies

GET api/v1/currencies/:code

Returns a single currency or all currencies available.

User token is required.

Resource parameter `code` [String] is optional.

Response Data Returned

If `code` is supplied, then an Currency Object is returned:

"data": {
    "currency": [Currency Object] {
        "code": [String],
        "title": [String],
        "date_modified": [String],
        "symbol_left": [String],
        "symbol_right": [String],
        "selected": [Boolean]
    }
}

Currency Object will include the attribute "selected" only for the currency currently set for the user session and it will be equal to boolean `true`.

If no `code` is supplied, then an array of Currency Objects are returned:

"data": {
    "currencies": [Array of Currency Objects]
}

NOTE: currencies are updated once a day.

api/v1/payments

GET api/v1/payments/:payment_no

Returns a payment.

User token and login is required.

Resource parameter: `payment_no` [String] is optional.

Response Data Returned

If a `payment_no` is supplied, then an Payment Object is returned:

"data": {
    "payment": {
        "payment_no": [String],
        "status": [String or Null],
        "payment_method": [Object] {
            "type": [String],
            "description": [String],
            "data": [Object]
        },
        "profile": [Object] {
            "profile_id": [String],
            "profile_name": [String],
            "profile_url": [String]
        },
        "tips": [Array of Objects] [{
            "link": [String],
            "title": [String],
            "note": [String],
            "total": [Float],
            "total_formatted": [String],
        }],
        "total": [Float],
        "total_formatted": [String],
        "currency_code": [String],
        "comment": [String],
        "payer": [Object] {
            "guest": [Boolean],
            "firstname": [String],
            "lastname": [String],
            "email": [String],
            "phone": [String],
            "phone_alt": [String],
            "payment_address": [Address Object] {
                "address_id": [Integer],
                "firstname": [String],
                "lastname": [String],
                "company":  [String],
                "company_id": [String],
                "address_1": [String],
                "address_2": [String],
                "city": [String],
                "postcode": [String],
                "zone": [Zone Object] {
                    "zone_id": [Integer], 
                    "zone_name": [String], 
                    "zone_code": [String]
                },
                "country": [Country Object] {
                    "country_id": [Integer], 
                    "country_name": [String], 
                    "country_code": [String]
                }
            }
        },
        "date_added": [String]
        "date_modified": [String]
    }
}

If no `payment_no` is supplied, then an array of `payment_no` [String] are returned:

"data": {
    "payments": [Array of Strings]
}

POST api/v1/payments

Creates a new payment for all tips of the user session for the payment method, payment profile, and payment address provided.

User token is required.

Request Body Parameters

Guest Payments

Request body parameters `phone_alt` is optional, as are `company`, `company_id`, and `address_2` attributes of the `payer_address` object.

{
    "guest": [Boolean] (`true`),
    "payment_method": [String] ('paypal' or 'check'),
    "payment_profile": [String] (Profile ID, e.g. 'UP-1234XXXX-1'),
    "email": [3-254 valid characters in email address format, String],
    "phone": [max 32 characters, String],
    "phone_alt": [max 32 characters, String],
    "payer_address": [Object] {
        "firstname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
        "lastname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
        "company":  [0-32 characters, String],
        "company_id": [0-32 characters, String],
        "address_1": [3-128 characters, String],
        "address_2": [0-128 characters, String],
        "postcode": [2-10 characters, String],
        "city": [2-128 characters, String],
        "zone_id": [Integer],
        "country_id": [Integer]
    },
    "comment": [0-5000 characters, String]
}

User Logged In & Existing Payment Address

Request body paramter `comment` is optional, as is `address_id` when `payment_address` is set to "default".

{
    "payment_method": [String] ('paypal' or 'check'),
    "payment_profile": [String] (Profile ID, e.g. 'UP-1234XXXX-1'),
    "payment_address": [String] ('existing' or 'default'),
    "address_id": [Integer] (required for 'existing' only),
    "comment": [0-5000 characters, String]
}

User Logged In & New Payment Address

Attributes `company`, `company_id`, and `address_2` of the `payer_address` request body parameter is optional.

{
    "payment_method": [String] ('paypal' or 'check'),
    "payment_profile": [String] (Profile ID, e.g. 'UP-1234XXXX-1'),
    "payment_address": [String] ('new'),
    "payer_address": [Object] {
        "firstname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
        "lastname": [3-32 alphabetic characters with hyphen and spaces allowed, String],
        "company":  [0-32 characters, String] (optional),
        "company_id": [0-32 characters, String] (optional),
        "address_1": [3-128 characters, String],
        "address_2": [0-128 characters, String] (optional),
        "postcode": [2-10 characters, String],
        "city": [2-128 characters, String],
        "zone_id": [Integer],
        "country_id": [Integer]
    },
    "comment": [0-5000 characters, String]
}

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String],
    "payment": [Payment Object]
}

POST api/v1/payments/:payment_no/pay

Updates the payment status of a payment.

User token is required.

Resource parameter `payment_no` [String] is required.

Request Body Parameters

Request body parameter `payment_status_id` is required.

{
    "payment_status_id": [Integer]
}

For now, `payment_status_id` must be set equal to "1", which indicates "Pending". Additional payment statuses will be added in the future.

Response Data Returned

"data": {
    "success": [Boolean],
    "message": [String]
}

0 tips - $0.00

My Tips

Tipalink API

API INTRO

API REQUESTS

Authentication

API Keys

User Tokens

Rate Limits

IP Whitelisting

API RESPONSES

API ERRORS

General Errors

POST Request Errors

API Key Validation Errors

API Endpoint Errors

API ENDPOINTS

api/v1/login

POST api/v1/login

Request Body Parameters

Response Data Returned

api/v1/logout

GET api/v1/logout

Response Data Returned

api/v1/account

GET api/v1/account

Response Data Returned

POST api/v1/account

Request Body Parameters

Response Data Returned

api/v1/addresses

GET api/v1/addresses/:address_id

Response Data Returned

POST api/v1/addresses/:address_id

Request Body Parameters

Response Data Returned

api/v1/profiles

GET api/v1/profiles/:profile_id

Response Data Returned

POST api/v1/profiles

Request Body Parameters

Response Data Returned

api/v1/images

POST api/v1/images

Request Body Parameters

Response Data Returned

api/v1/tips

GET api/v1/tips/:key

Response Data Returned

POST api/v1/tips/:key

Request Body Parameters

Response Data Returned

api/v1/countries

GET api/v1/countries/:country_id

Response Data Returned

GET api/v1/countries/:country_id/zones/:zone_id

Response Data Returned

api/v1/zones

GET api/v1/zones/:zone_id

Response Data Returned

api/v1/currencies

GET api/v1/currencies/:code

Response Data Returned

api/v1/payments

GET api/v1/payments/:payment_no

Response Data Returned

POST api/v1/payments

Request Body Parameters

Guest Payments

User Logged In & Existing Payment Address

User Logged In & New Payment Address

Response Data Returned

POST api/v1/payments/:payment_no/pay

Request Body Parameters

Response Data Returned

Login

Join Us

Send A Message