Welcome to the API Documentation of Ratecard.io. This documentations describes the functionality of our API. If you need any support or help please contact our support via support@ratecard.io or call 088 35 35 135

Oauth 2.0

In order to make authorized calls to Ratecard API, your application must first obtain an OAuth access token on behalf of a Ratecard user.

The 3-legged OAuth flow allows your application to obtain an access token by redirecting a user to Ratecard and having them authorize your application. The user will always be prompted to authorize access to your application.

Our platform accepts 2 different authorization methods. The Authorization code authorization which is used for third party implementors accepted by Ratecard. And Client credential authorizatrions, which is best suited to connect your own rate card to your own website or application.

To apply for a Authorization code implementation we need to grant you access to this, a redirect url is required and needs to be supplied to us. Contact us at support@ratecard.io or call 088 35 35 135

    [POST] https://ratecard.io/oauth/authorize

    [POST] https://ratecard.io/oauth/access_token
Parameter type default description
client_id string The obtained client_id for the Ratecard API
client_secret string The obtained client_secret obtained at the Ratecard API

Response

Parameter type default description
code string The authorization token used to get access to the api
state string Api response state parameter

Accounts

The accounts API gives access to the individual Ratecards.

get user related accounts [/api/v1/accounts]

Get the account connected to the authenticated user.

    [GET] https://ratecard.io/api/v1/accounts

Response

Parameter type default description
name string The name of the specific ratecard
auth_token string The ratecard account_id authentication token, this is used to fetch the details of the specific ratecard.
Markup

            [
  {
    "name": "John Doe",
    "auth_token": "AezYT01P5dJ6YsIG"
  },
  {
    "name": "Company example bv",
    "auth_token": "a83nfFjfGGHWjgiA"
  }
]
            

Search account [/api/v1/accounts/search]

Search for ratecard. Use one of the listed post parameters (at leat one). Max results 10

    [POST] https://ratecard.io/api/v1/accounts/search

Post parameters

Parameter type default description
access_token* string Your access token received upon Oauth consent
name string Search on freelancer or company name
skill string Search on skill related to the ratecard (only applies to freelancer)
city string Search on the ratecard location (city)
country string Search on the ratecard location (country)
email string Search on the ratecard email
phone string Search on the ratecard phone number
min_reviews integer Searches on ratecards with at least min_reviews of reviews
max_reviews integer Searches on ratecards with a maximum of max_reviews of reviews
min_rating integer Searches on ratecards with at least min_rating rating
max_rating integer Searches on ratecards with a maximum of max_rating rating

Response

Parameter type default description
account_id string The unique review id
name string The name of the specific ratecard
logo url Logo url of the ratecard if this exists
url url The ratecard profile URL
review_url url The direct url to the ratecard profile review page
score float The avarage score of the ratecard
reviews integer The amount of reviews in this ratecard
nps integer The current avrage NPS score of this ratecard -100 to 100
city string The city where the Ratecard is located
country string The country where the Ratecard is located
skills array (string) The skills of the specific account (only applies on freelancers)
Markup

[
  {
    "account_id": "ew9fn20",
    "name": "John Doe",
    "logo": "https://ratecard.io/logo.png",
    "url": "https://ratecard.io/john-doe",
    "review_url": "https://ratecard.io/john-doe/review",
    "score": 8.5,
    "reviews": 12,
    "nps": 65,
    "city": "Amsterdam",
    "country": "NL"
    "skills": {
          "skill1",
          "skill2"
    }
  }
]
            

Create account [/api/v1/accounts/create]

Create a new ratecard account. All newly created ratecard accounts will be added pending approval.

    [POST] https://ratecard.io/api/v1/accounts/create

Post parameters

Parameter type default description
access_token* string Your access token received upon Oauth consent
name* string Company or freelancer name
account_type* string The user type, allowed values: freelancer, client, staffing agency
company_website url The account company_website
email string The account email
phone string The account phone
address string The account address
postal_code string The account postal_code
city string The account city
country string The account country example NL UK DE FR ...
description text The account description
industry text The account industry, Click here for the allowed industries
linkedin url The account linkedin profile
facebook url The account facebook profile
twitter url The account twitter profile
glassdoor url The account glassdoor profile

Response

Parameter type default description
message string The success or error message
name string The name of the specific ratecard
url url The ratecard profile URL
account_id url The unique account id
Markup

[
  {
    "message": "Account succesfully created",
    "name": "John Doe",
    "url": "https://ratecard.io/john-doe",
    "account_id": "ew9fn20"
  }
]
            

Create contacts for account [/api/v1/accounts/contacts/create]

Create new contact for a ratecard account

    [POST] https://ratecard.io/api/v1/accounts/contacts/create

Post parameters

Parameter type default description
access_token* string Your access token received upon Oauth consent
account_id* string The account id
first_name* string The first name for the contact
last_name* string The last name for the contact
email* string A valid and unique email for the contact
language* string A valid language, valid values: nl, en

Response

Parameter type default description
message string The success or error message
Markup

[
  {
    "first_name": "John",
    "last_name": "Doe",
    "message": "Contact successfully created",
    "user_id": "29fn20fn0f"
  }
]
            

get account contacts [/api/v1/accounts/*account_id*/contacts]

get the associated contacts from a account. get the account_id via get accounts endpoint.

    [GET] https://ratecard.io/api/v1/accounts/*account_id*/contacts

Response

Parameter type default description
user_id string The user id
review url string The account and user specific review url
Markup

[
  {
    "user_id": "19fb10f",
    'firstname' => "John",
    'lastname' => "Doe",
    "review_url": "https://ratecard.io/john-doe/review/1r9fb9baf",
  },
  {
    "user_id": "19fb10f",
    'firstname' => "John",
    'lastname' => "Doe",
    "review_url": "https://ratecard.io/john-doe/review/1r9fb9baf",
  }
]
            

get contact details [/api/v1/contacts/*user_id*]

Get the user details. get the user_id via get accounts related users endpoint.

    [GET] https://ratecard.io/api/v1/contacts/*user_id*

Response

Parameter type default description
user_id string The user id
review url string The account and user specific review url
Markup

[
  {
    "user_id": "19fb10f",
    'firstname' => "John",
    'lastname' => "Doe",
    "review_url": "https://ratecard.io/john-doe/review/1r9fb9baf",
  }
]
            

get account details [/api/v1/accounts/*account_id*]

Get the account details connected to the account_id fetched in the get user related accounts endpoint or an unique email address or phone number.

    [GET] https://ratecard.io/api/v1/accounts/*account_id*

Response

Parameter type default description
account_id string The account id
name string The name of the specific ratecard
logo url Logo url of the ratecard if this exists
url url The ratecard profile URL
review_url url The direct url to the ratecard profile review page
score float The avarage score of the ratecard
reviews integer The amount of reviews in this ratecard
nps integer The current avrage NPS score of this ratecard -100 to 100
city string The city where the Ratecard is located
country string The country where the Ratecard is located
skills List of custom skills (only applied to freelancers)
- name string Name of the custom skill
- avarage_score float(2,1) 0 Avarage score of the skill
Markup

[
  {
    "account_id": "19fb10f",
    "name": "John Doe",
    "logo": "https://ratecard.io/logo.png",
    "url": "https://ratecard.io/john-doe",
    "review_url": "https://ratecard.io/john-doe/review",
    "score": 8.5,
    "reviews": 12,
    "nps": 65,
    "city": "Amsterdam",
    "country": "NL"
    "skills": [
      {
        "name": "skill1",
        "avarage_score": 10
      },
      {
        "name": "skill2",
        "avarage_score": 5
      }
    ]
  }
]
            

Get recent reviews from account [/api/v1/accounts/*account_id*/reviews]

Get the recent reviews from a specific account. This get be fetched with a account account_id which get be collected in the get user related accounts endpoint. Max results 5

    [GET] https://ratecard.io/api/v1/accounts/*account_id*/reviews

Response

Parameter type default description
review_id string The unique id of the review
url url The direct url to the review
review_url url The direct url to the review url
profile_url url The direct url to the ratecard profile
title string The direct url to the review
description text Returns the review of max 50 characters
score float The review score
relationship string Returns the relationship
language string Returns the language code (en, nl, de)
Markup

 [
  {
    "review_id": "d1nf01nf",
    "url": "https://ratecard.io/account-slug/160711-review-slug",
    "review_url": "https://ratecard.io/account-slug/review",
    "profile_url": "https://ratecard.io/account-slug",
    "title": "A great review",
    "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusantium ad",
    "score": 8.36,
    "relationship": "Client, customer and/or hirer (hiring party)",
    "language": "nl"
  },
  {
    "review_id": "a0551nf",
    "url": "https://ratecard.io/account-slug/160711-review-slug-2",
    "review_url": "https://ratecard.io/account-slug/review",
    "profile_url": "https://ratecard.io/account-slug",
    "title": "A great review 2",
    "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusantium ad",
    "score": 9.5,
    "relationship": "Client, customer and/or hirer (hiring party)",
    "language": "en"
  },
]
            

Get review details [/api/v1/accounts/*account_id*/reviews/*review_id*]

Get a single review from a specific account with the account_id fetched via: get user related accounts endpoint. and the review_id fetched via: get reviews from account

    [GET] https://ratecard.io/api/v1/accounts/*account_id*/reviews/*review_id*

Response

Parameter type default description
review_id string The unique review id
url url The direct url to the review
profile_url url The direct url to the ratecard profile
review_url url The direct url to the review url
title string The direct url to the review
description text Returns the review of max 50 characters
score float The review score
relationship string Returns the relationship
language string the language code (en,nl,de)
Markup

 [
  {
    "review_id": "d93nf0fbn",
    "url": "https://ratecard.io/account-slug/160711-review-slug",
    "profile_url": "https://ratecard.io/account-slug",
    "review_url": "https://ratecard.io/account-slug/review",
    "title": "A great review",
    "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. Accusantium ad",
    "score": 8.36,
    "relationship": "Client, customer and/or hirer (hiring party)",
    "language": "nl",
  }
]
            

Get account widgets [/api/v1/accounts/*account_id*/widgets]

Get the account related widgets. This can be fetched with a account account_id which get be collected in the get user related accounts endpoint.

    [GET] https://ratecard.io/api/v1/accounts/*account_id*/widgets

Response

Parameter type default description
widget string The widget name
url url The direct url to the widget file
Markup

 [
  {
    "name": "widget1",
    "url": "https://ratecard.io/widget/1235/sadfjbsadfbsa83939/rc_w1.js"
  },
  {
    "name": "widget2",
    "url": "https://ratecard.io/widget/1235/sadfjbsadfbsa83939/rc_w2.js"
  },
  {
    "name": "widget3",
    "url": "https://ratecard.io/widget/1235/sadfjbsadfbsa83939/rc_w3.js"
  },
  {
    "name": "widget4",
    "url": "https://ratecard.io/widget/1235/sadfjbsadfbsa83939/rc_w4.js"
  },
]
            

Requests

Create a new review request to keep track or send out requests throughout the Ratecard engine. At the moment we have 3 types op review request: Quick request, invoice request or project request.

For example when you send out an invoice, you can add a review request to this to track the score of this specific project or service. The review requests can also be used to send our request by mail via Ratecard.

Create quick request [/api/v1/review_request]

The purpose of this request is to sent a one-way review request.

    [POST] https://ratecard.io/api/v1/review_request

Post parameters

Parameter type default description
access_token* string Your access token received upon Oauth consent
account_id* string The auth_token of a specific connected ratecard, this can be received from the /accounts api endpoint
firstname* string firstname of the person you are requesting a review from
lastname* string lastname of the person you are requesting a review from
email* string The email of the person you are requesting a review from
language* string Language of the request (either nl or en)
send_mail boolean false Send a request e-mail automatically by date and time if send_date is filled or directly when empty. Format yyyy-mm-dd hh:mm:ss
send_date dattime The time the request should be mailed (only if send_mail is set to 1 or true). Format yyyy-mm-dd hh:mm:ss

Response

Parameter type default description
message string Success or error message
token string The unique request token of the review_request, this can be stored to later request the status
review_url url A url that can be used right away for a referred review.
Markup

[
  {
    "message": "Request succesfully added",
    "token": "rQ346014071478",
    "review_url": "https://ratecard.io/robbie-sakkers/review?tk=rQ346014071478"
  }
]
            

Create invoice request [/api/v1/invoice_request]

This type of review request is especially made for accounting/ billing applications to verify the contact information, relationship and billing information.

    [POST] https://ratecard.io/api/v1/invoice_request

Post parameters

Parameter type default description
access_token* string Your access token received upon Oauth consent
account_id* string The auth_token of a specific connected ratecard, this can be received from the /accounts api endpoint
firstname* string firstname of the person you are requesting a review from
lastname* string lastname of the person you are requesting a review from
email* string The email of the person you are requesting a review from
language* string en The language code for the specific invoice (nl or en)
company_name* string Company name
relationtype* string Relationtype, check out our relationtypes we accept.
phone integer The phone number of the client (format 1234567891) only numbers
total_amount string Invoice total incl. tax 1234.56
currency string Currency specified on invoice (example USD, EUR).
invoice_date string Invoice date (format: yyyy-mm-dd)
invoice_due_date string Due date (format: yyyy-mm-dd)
invoice_status string Status of invoice (example partial_payment, full_payment, overdue_payment, client_viewed, unpaid_payment) check out our invoice status we accept.
send_mail boolean false Send a request e-mail automatically by date and time if send_date is filled or directly when empty. Format yyyy-mm-dd hh:mm:ss
send_date dattime The time the request should be mailed (only if send_mail is set to 1 or true). Format yyyy-mm-dd hh:mm:ss

Response

Parameter type default description
message string Success or error message
token string The unique request token of the invoice_request, this can be stored to later request the status
review_url url A url that can be used right away for a referred review.
Markup

[
  {
    "message": "Request succesfully added",
    "token": "rQ346014071478",
    "review_url": "https://ratecard.io/robbie-sakkers/review?tk=rQ346014071478"
  }
]
            

Create project request [/api/v1/project_request]

This type of review request is especially made to use in the process of an project/ placement where multiple parties (more than 2) are involved (for example: Client, intermediairy and/ or freelancer/ candidate).

    [POST] https://ratecard.io/api/v1/project_request

Post parameters

Parameter type default description
access_token* string Your access token received upon Oauth consent
account* string The auth_token of a specific connected ratecard, this can be received from the /accounts api endpoint
start_date* string Project start date. Format yyyy-mm-dd
end_date* string Project end date. Format yyyy-mm-dd
reference* string The unique reference of the project.
language* string The project language and default language to be used for optional email notifications en or nl.
send_mail boolean false Send a request e-mail automatically by date and time if send_date is filled or directly when empty. Format yyyy-mm-dd
contacts* json The contacts of the specific project.

Json example contacts

Parameter type default description
name* string The company name
firstname* string First name of the contact person
lastname* string The last name of the contact person
email* string Emailaddress of the contact person
type* string The type of contact, available options: worker supplier client
Markup

  [
    {
      "name":"Company 1",
      "firstname":"John",
      "lastname":"Doe",
      "email":"john.doe@company.com",
      "type":"client",
      "language":"nl"
    },
    {
      "name":"Company 2",
      "firstname":"John",
      "lastname":"Doe",
      "email":"john.doe@company2.com",
      "type":"worker",
      "language":"en"
    },
    {
      "name":"Company 3",
      "firstname":"John",
      "lastname":"Doe",
      "email":"john.doe@company3.com",
      "type":"supplier",
      "language":"en"
    }
  ]
            

Response

Parameter type default description
message string Success or error message
token string Unique project token
requests array Array of the generated requests
- email string The emailaddress of the reviewer
- review_url string The first review url for the specific reviewer
Markup

{
  "message": "Project succesfully added",
  "token": "rQp08201108",
  "requests": [
    {
      "email": "john.doe@company1.com",
      "review_url": "https://ratecard.io/company2/review?tk=rQpU658044311085&locale=nl&source=018dkd9"
    },
    {
      "email": "john.doe@company2.com",
      "review_url": "https://ratecard.io/company1/review?tk=rQpU428000331086&locale=nl&source=018dkd9"
    },
    {
      "email": "john.doe@company3.com",
      "review_url": "https://ratecard.io/company1/review?tk=rQpU915244350000&locale=en&source=018dkd9"
    }
  ]
}
            

Status of review request [/api/v1/review/*token*]

Get the status of the review by token obtained via Get account details, quick request, invoice request or project request.

    [GET] https://ratecard.io/api/v1/review/*token*

Response

Parameter type default description
message string Success or error message
token string The unique request token of the review_request, this can be stored to later request the status
review_url url A url that can be used right away for a referred review.
status boolean If a review has been completed or not returning true or false.
review Returning the review if it has been completed
url url The direct url to the review
title string The direct url to the review
description text Returns the review of max 50 characters
score float The review score
relationship string Returns the relationship
Markup

{
  "token": "rQ4035111",
  "review_url": "https://ratecard.io/ratecardio/review/rQ4035111",
  "status": true,
  "review": {
    "url": "https://ratecard.io/ratecardio/m2em7btkl7-the-original-url",
    "title": "This is the test title of the review",
    "description": "Lorem ipsum dolor sit amet, consectetur adipisicing elit. ",
    "score": 9.76,
    "relationship": "Directly hired as a freelancer and/or independent contractor (business)"
  }
}