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.

Production endpoint: https://iplan.co.il/he-IL/api/corp
Staging endpoint: https://staging2.iplan.co.il/he-IL/api/corp

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:

Content-Type: application/json

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", ...}

You must replace my_api_key with your 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

You’re getting error “no ‘Access-Control-Allow-Origin’ header is present on the requested resource” - you’re trying to access API from browser javascript (AJAX). This is a server to server API, you need to submit your form to your webserver, from there make an API request, process response and render back the relevant response to client.

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

Ubeya/events

List Events [Get]

Example of success request:

r = HTTParty.get('https://iplan.co.il/he-IL/api/corp/ubeya/events.json', :headers => { 'Content-Type' => 'application/json' }, :body=>{:api_key=>"my_api_key", :from_date=>'2017-01-01', :to_date=>'2017-01-01'}.to_json)

GET /he-IL/api/corp/ubeya/events.json HTTP/1.1
Host: iplan.co.il:443
Content-Type: application/json
{"api_key": "my_api_key",  :from_date": "2017-01-01", "to_date": "2017-03-01"}

Response

puts r.code
# would print: 200
pp r.parsed_response
# would print
  {
    "events"=>
      [
        {
          "estimated_guest_count"=>nil,
          "id"=>3203,
          "index"=>182,
          "title"=>"חתונה #182",
          "updated_at"=>"2017-11-27T11:48:23+02:00",
          "start_at_date"=>"2011-09-08",
          "start_at_time"=>"20:45",
          "end_at_time"=>"23:45",
          "event_location"=>
           {
            "name"=>"אולם ומלואו",
            "coordinates"=>{"longitude"=>23.5247249, "latitude"=>51.1381044},
            "address"=>"הדרך 24, חלם"
           },
          "event_type"=>"חתונה",
          "minimum_guests"=>1,
          "color"=>"#96ed96",
          "url"=>"https://iplan.co.il/he-IL/corp/companies/123/company_events/3203"
         },
         {
          "estimated_guest_count"=>385,
          "id"=>3211,
          "index"=>190,
          "title"=>"דני ודנה",
          "updated_at"=>"2017-11-27T11:48:23+02:00",
          "start_at_date"=>"2013-01-01",
          "start_at_time"=>"19:30",
          "event_location"=>
           {
            "name"=>"אולם ומלואו",
            "coordinates"=>{"longitude"=>23.5247249, "latitude"=>51.1381044},
            "address"=>"הדרך 24, חלם"
           },
          "event_type"=>"חתונה",
          "color"=>"#96ed96",
          "url"=>"https://iplan.co.il/he-IL/corp/companies/123/company_events/3211"
          }
    ],
    "total_results"=>1442,
    "status" => "ok"
  }

HTTP/1.1 200 OK
Date: Mon, 21 Apr 2014 13:26:48 GMT
Content-Type: application/json; charset=utf-8
{
  "events"=>
    [
      {
        "estimated_guest_count"=>nil,
        "id"=>3203,
        "index"=>182,
        "title"=>"חתונה #182",
        "updated_at"=>"2017-11-27T11:48:23+02:00",
        "start_at_date"=>"2011-09-08",
        "start_at_time"=>"20:45",
        "end_at_time"=>"23:45",
        "event_location"=>
         {
          "name"=>"אולם ומלואו",
          "coordinates"=>{"longitude"=>23.5247249, "latitude"=>51.1381044},
          "address"=>"הדרך 24, חלם"
         },
        "event_type"=>"חתונה",
        "minimum_guests"=>1,
        "color"=>"#96ed96",
        "url"=>"https://iplan.co.il/he-IL/corp/companies/123/company_events/3203"
       },
       {
        "estimated_guest_count"=>385,
        "id"=>3211,
        "index"=>190,
        "title"=>"דני ודנה",
        "updated_at"=>"2017-11-27T11:48:23+02:00",
        "start_at_date"=>"2013-01-01",
        "start_at_time"=>"19:30",
        "event_location"=>
         {
          "name"=>"אולם ומלואו",
          "coordinates"=>{"longitude"=>23.5247249, "latitude"=>51.1381044},
          "address"=>"הדרך 24, חלם"
         },
        "event_type"=>"חתונה",
        "color"=>"#96ed96",
        "url"=>"https://iplan.co.il/he-IL/corp/companies/123/company_events/3203"
       }
    ],
  "total_results"=>1442,
  "status"=>"ok"
}

Error example

   puts r.code
   # would print: 422
   pp r.parsed_response
   # would print { "status": "validation_failed", "message": "validation failed","errors"=>{"from_date"=>["הוא לא מספר"]} }

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"=>{
    "from_date"=>["הוא לא מספר"]
  }
}

Get a list of closed events from CRM. Full action url: https://iplan.co.il/he-IL/api/corp/ubeya/events.json

Request parameters

Parameter	Type	Required	Description
from_date	string	yes	ISO8601 date format (YYYY-MM-DD) return events from this date. The date must be later than beginning of last month.
to_date	string	yes	ISO8601 date format (YYYY-MM-DD). return events up to this date

Response parameters

Parameter	Type	Guaranteed	Description
“events”	array	yes	Array of Event objects, maximum 1000
“total_results”	integer	yes	Total amount of events that match the request parameters.
“status”	string	yes	“ok” for successful request, “validation_failed” for problems with request parameters or either of error statuses specified in Introduction>Errors section
“errors”	object	no	When the status is “validation_failed” this will hold a description of errors if available
“message”	string	no	A short explanation of the status if it was not “ok”

Event

Parameter	Type	Guaranteed	Description
“id”	integer	yes	ID unique to this event in the system, used for API calls
“index”	integer	yes	ID unique to this event within the company, used for display
“title”	string	yes	The title or name of the event
“updated_at”	string	yes	ISO8601 (YYYY-MM-DDThh:mm:ss±hh:mm) format of date & time of the last update to this event
“event_location”	Location	no	The location object for the event
“event type”	String	yes	The type of the event, should be treated as free text rather than an enum.
“minimum_guests”	integer	no	Minimum number of guests the customers committed to
“color”	string	no	Color of event in calendar in rgb hex color (e.g. “#0000ff” for blue)
“url”	string	yes	url of the event in the CRM

Location

Parameter	Type	Guaranteed	Description
“name”	string	yes	The name of the location
“address”	string	no	Address line of the location
“coordinates”	Coordinates	no	GPS coordinates object of the location

Coordinates

Parameter	Type	Guaranteed	Description
“longitude”	float	yes	Longitude part of the coordinate in decimal degrees format (North)
“latitude”	float	yes	Latitude part of the coordinate in decimal degrees format (West)