NAV
Ruby HTTP

Introduction

Our API is organized around REST with JSON responses. Our API is designed to use HTTP response codes to indicate API success/errors. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Environments

We have two environments - production and staging. The staging environment should be used during development and testing.

Making requests

All request and response bodies, including errors, are encoded in JSON with UTF-8 encoding.

Always set the following headers as part of your request:

This is a server to server API, requests from within the browser (AJAX) are NOT supported. This is by design, as API keys are private, and should not be exposed to clients via javascript.

Authentication

We use API keys to allow access to our API. If your company has paid for API access, you can receive your API key from our vendors support.

The API key must be included in all API requests to the server as part of every JSON body via api_key attribute.

{"api_key": "my_api_key", ...}

Errors

For example, response with invalid api key request would look like:

require 'httparty'
r = HTTParty.post('https://iplan.co.il/he-IL/api/corp/leads.json', :headers => { "Content-Type" => "application/json" }, :body=>{ api_key: "some_invalid_key", form_id: 123456789, "contact_full_name": "test checker", "contact_email": "test@test.com", "request_content": "test creating form request via api", "request_matter": "interested in event"}.to_json )
puts r.code
# would print: 401
puts r.parsed_response.inspect
# would print: {"status": "bad_credentials", "message": "invalid api_key"}

HTTP/1.1 401 Unauthorized
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8

{
    "status": "bad_credentials",
    "message": "invalid api_key"
}

If an error occurs, the API will respond with the appropriate HTTP status code and json error message object which contains the following keys:

Key Type Description
status string One of the status strings described below
message string Humanly readable message with more details

Possible status values and their meaning:

Status HTTP status code Meaning
bad_request 400 The request was malformed.
bad_credentials 401 Invalid api key was used to authenticate the request.
ip_not_allowed 401 The api key is valid, but need to access from ip that is allowed
permission_denied 403 The api key is valid, but does not have the required permissions to access the requested resource or perform the requested action.
not_found 404 The requested resource does not exist or is not publicly available.
validation_failed 422 Request could not be performed due to validation errors

Troubleshooting

Contact form messages

Create new message [POST]

Example of success request:

require 'httparty'
r = HTTParty.post('https://iplan.co.il/he-IL/api/corp/leads.json', :headers => { "Content-Type" => "application/json" }, :body=>{ api_key: "my_api_key", form_id: 123456789, "contact_full_name": "test checker", "contact_email": "test@test.com", "request_content": "test creating form request via api", "request_matter": "interested in event"}.to_json )

POST /he-IL/api/corp/leads.json HTTP/1.1
Host: iplan.co.il:443
Content-Type: application/json

{"api_key": "my_api_key", "form_id": 123456789, "contact_full_name": "test checker", "contact_email": "test@test.com", "request_content": "test creating form request via api", "request_matter": "interested in event"}

Response

puts r.code
# would print: 200
puts r.parsed_response.inspect
# would print {"status": "ok", "message_id": 12345}

HTTP/1.1 200 OK
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8

{
    "status": "ok",
    "message_id": 12345
}

Example request that would generate validation errors:

require 'httparty'
r = HTTParty.post('https://iplan.co.il/he-IL/api/corp/leads.json', :headers => { "Content-Type" => "application/json" }, :body=>{ api_key: "my_api_key", form_id: 123456789, "contact_email": "te@st@test.com", "request_content": "test creating form request via api", "request_matter": "interested in event"}.to_json )

POST /he-IL/api/corp/leads.json HTTP/1.1
Host: iplan.co.il:443
Content-Type: application/json

{"api_key": "my_api_key", "form_id": 1234, "contact_email": "te@st@test.com", "request_content": "test creating form request via api", "request_matter": "interested in event"}

Response

puts r.code
# would print: 422
puts r.parsed_response.inspect
# would print { "status": "validation_failed", "message": "validation failed", "errors": { "contact_full_name": "must be present", "contact_email": "invalid format" } }

HTTP/1.1 422 Unprocessable Entity
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8

{
    "status": "validation_failed",
    "message": "validation failed",
    "errors": {
      "contact_full_name": "must be present",
      "contact_email": "invalid format"
    }
}

Create new contact form message in CRM. Note that the request must be a POST request.

Full action url: https://iplan.co.il/he-IL/api/corp/leads.json

Request parameters

Parameter Type Required Description
form_id integer true Id of the contact form in CRM with which the created message would be associated. This value either would be provided to you by support staff or if you have access to CRM interface, you go to screen מאגרים > טפסי פנייה and take value of קוד column (without the #) of relevant contact form
contact_full_name string true Full name of the person submitting a contact request (max length: 100 chars)
contact_email string true
if contact_phone empty		 Valid email address of the person submitting a contact request. Either contact_email or contact_phone must be present (max length: 100 chars)
contact_phone string true
if contact_email empty		 Phone number of the person submitting a contact request. Either contact_email or contact_phone must be present (max length: 20 chars)
request_matter string false Subject or matter type text upon which the contact form is made. If left blank, would default to: “Request received via API” (max length: 20 chars)
request_content string true request/description customer submitted to the form (max length: 1024 chars)

Response parameters

When message created successfully, would return JSON the following keys:

Parameter Type Description
status string value of “ok”
message_id integer ID of the newly created message

When message fails to create because of validation errors, would return response with 422 http status and JSON body the following keys:

Parameter Type Description
status string value of “validation_failed”
message string value of “validation failed”
errors object object containing errors for each attribute that failed to validate
Ruby HTTP