Yes-co Open API

Yes-co Open API

  • The API is a RESTfull service
  • The API supports both JSON and XML output formats. Use the ?format=xml or ?format=json to change output format. The default output format is JSON.

API Objects

  • Most objects (projects, relations, notes, images etc.) are available through the Yes-co Open API.
    • Use HTTP/1.1 GET request to retrieve objects
    • Use HTTP/1.1 POST request to add/modify objects
    • Use HTTP/1.1 DELETE request to remove objects
  • All objects in Yes-co Open have a unique id, the API Object ID.
    • There is one special API Object ID, called ‘session’. This object refers to a Yes-co Open browser session, which does the same thing as logging in at https://login.yes-co.com with a web browser.
  • All requests follow a standard URL scheme
    • https://api.yes-co.com/1.0/ or
    • https://api.yes-co.com/1.0/:apiObjectId/

Project

ProjectCreate

  • Creates a new project entity
  • This is a HTTP/1.1 POST request
  • Url: https://api.yes-co.com/1.0/:apiObjectId/project
  • apiObjectId is the API id of the parent project, linked office of linked employee

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1
scenario (required)
Scenario of project (BBvk, BBvh, NBvk, etc…)
type (required for BBvk, BBvh, NBvk, NBty, BOvk and BOvh)
Type of project (Woonruimte, etc…)
See project for possible scenario/type/subtype combinations
subtype (required for BBvk, BBvh, NBvk, NBty, BOvk and BOvh)
Sub type of project (Woonhuis, Appartement, etc…)
See project for possible scenario/type/subtype combinations
name (required)
Display name of the project (Rondinweg 63)
country (required when rest of address is set)
Country from project address
city (required when rest of address is set, except for NBpr)
City from project address
street (required when rest of address is set, except for NBpr)
Street from project address
zipcode (required when rest of address is set, except for NBpr)
Zipcode from project address
housenumber (required when rest of address is set, except for NBpr)
House number from project address
housenumber_addition
House number addition from project address

Response

API object id of the created of project, this can be used to display the project with the navigate call

 integer(5) "84325"

ProjectList

  • Retrieves a list of projects
  • This is a HTTP/1.1 GET request
  • Url: https://api.yes-co.com/1.0/:apiObjectId/project
  • apiObjectId is the API id of the parent project, linked office of linked employee

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1

Response

List containing project id’s (API Object ID’s)

array(16) {
   [1]=>
     array(1) {
       [2]=>
         array(1) {
           [3]=>
             string(10) "1260556652"
         }
     }
   [4]=>
     array(1) {
       [5]=>
         array(1) {
           [6]=>
             string(10) "1934818301"
         }
     }

ProjectSearch

  • Retrieves a list of projects with specified criterea
  • This is a HTTP/1.1 GET request
  • Url: https://api.yes-co.com/1.0/search

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1
date (optional)
- type (required)
Type of search. Values doc and dlm are accepted
- from (required)
Search from this date (YYYY-MM-DD)
- till (optional)
Search till this date (YYYY-MM-DD)
sort (optional)
- field (optional)
Field to sort. Values doc and dlm are accepted (dlm is default)
- direction (optional)
:D irection to sort. Values acending and descending are accepted (acending is default)
limit (optional)
Limit search result
offset (optional)
Skip x results in search result

Response

List containing project id’s (API Object ID’s)

array(1) {
[7]=>
array(10) {
[8]=>
array(1) {
[9]=>
array(7) {
[10]=>
string(9) "235561586"
[11]=>
string(20) "Carel Willinklaan 48"
[12]=>
string(19) "2012-09-20T09:11:36"
[13]=>
string(19) "2012-09-20T09:52:50"
[14]=>
string(4) "BBvk"
[15]=>
array(1) {
[16]=>
array(2) {
[17]=>
string(36) "ba51faf1-af15-4b06-9947-ebfe8f68c42f"
[18]=>
string(41) "http://webservice.yes-co.nl/media_service"
}
}
[19]=>
array(1) {
[20]=>
array(2) {
[21]=>
int(378179426)
[22]=>
string(41) "http://service.yes-co.nl/apixml/project10"
}
}
}
}
[23]=>
array(1) {
[24]=>
array(7) {
[25]=>
string(10) "2073117242"
[26]=>
string(14) "Kuifjestraat 1"
[27]=>
string(19) "2011-12-06T10:50:49"
[28]=>
string(19) "2012-10-01T01:44:40"
[29]=>
string(4) "BBvk"
[30]=>
array(1) {
[31]=>
array(2) {
[32]=>
string(36) "d7e957ec-75e2-4686-9f4d-bf0a6ac5d40d"
[33]=>
string(41) "http://webservice.yes-co.nl/media_service"
}
}
[34]=>
array(1) {
[35]=>
array(2) {
[36]=>
int(378179426)
[37]=>
string(41) "http://service.yes-co.nl/apixml/project10"
}
}
}
}
etc...

ProjectRetrieve

  • Retrieves the XML content of a single project object
  • This is a HTTP/1.1 GET request
  • Url: https://api.yes-co.com/1.0/

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1

Response

Project XML content (JSON output format is not possible).

<?xml version="1.0" encoding="UTF-8"?>
<Project xmlns="http://service.yes-co.nl/apixml/project10" timestampGenerated="2011-01-28T11:20:42+01:00" modifiedDate="2011-01-27T13:06:25+01:00" createdDate="2009-05-25T00:00:00+02:00" id="1766845205">
   <Scenario>BBvk</Scenario>
   <Type>Woonruimte</Type>
   <SubType>Woonhuis</SubType>
   <Archived>false</Archived>
   <Name>Capricciostraat 47 (voorbeeld woning verkoop)</Name>
   <YProjectNumber>1</YProjectNumber>
   <Status>
     <Description>verkocht onder voorbehoud</Description>
   </Status>
   <BBvk>
     <General>
       <Name>Capricciostraat 47</Name>
       <ObjectStatus>verkocht onder voorbehoud</ObjectStatus>
       <Voorbehoud>2010-10-31</Voorbehoud>
....
</Project>

Search Profile

searchProfileCreate

  • Creates a new search profile project entity
  • This is a HTTP/1.1 POST request
  • Url: https://api.yes-co.com/1.0/:apiObjectId/searchprofile
  • apiObjectId is the API id of the linked office or linked employee

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1
type (required)
Type of object searched, should always be ‘Woonruimte’
subtype (required)
Sub type of object searched, can be on of: ‘Woonhuis’, ‘Appartement’ or ‘Beide’
name (required)
Name of search profile
searcher_id (searcher_id or searcher_name + searcher_email is required)
API id of the linked relation (if it’s a already existing relation)
searcher_name (searcher_id or searcher_name + searcher_email is required)
Name of the linked relation
When searcher_name is provided, searcher_email should also be provided
A new relation is created and linked to the search profile
searcher_email (searcher_id or searcher_name + searcher_email is required)
E-mail address of the linked relation
When searcher_email is provided, searcher_name should also be provided
A new relation is created and linked to the search profile

Response

API object id of the created search profile project, this can be used to display the project with the navigate call

 integer(5) "84325"

searchProfileList

  • Retrieves a list of search profile projects
  • This is a HTTP/1.1 GET request
  • Url: https://api.yes-co.com/1.0/:apiObjectId/searchprofile
  • apiObjectId is the API id of the linked office or linked employee

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1

Response

List containing search profile project id’s (API Object ID’s)

array(2) {
   [38] =>
     array(1) {
       [39]=>
         array(2) {
           [40] => string(10) "1260556652"
           [41] => string(4) "WOzo"
         }
     }
   [42]=>
     array(1) {
       [43] =>
         array(2) {
           [44] => string(10) "1934818301"
           [45] => string(4) "WOzo"
         }
     }

Session

  • Url: https://api.yes-co.com/1.0/session

SessionOpen

  • Open a Yes-co Open session displaying a project or relation
  • This method is HTTP/1.1 POST

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1

Response

session
Session key and application server
 object(YisApiSession)#4 (2) {
[46]=>
string(32) "ef3fdcec8f170cce9dddef569cbe224b"
[47]=>
string(42) "https://app-s03-rb2e.yes-co.com/"
}

Note: Once a session is open, redirect the browser to ‘application server/sessionKey’ (e.g.: https://app-s03-rb2e.yes-co.com/ef3fdcec8f170cce9dddef569cbe224b) or set a cookie using the Javascript library.

SessionClose

  • Invalidate session key acquired by SessionOpen
  • This is a HTTP/1.1 DELETE request

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1

Response

String containing ‘closed’ status:

 string(6) "closed"

SessionPing

  • Check if acquired session is still valid
  • This method is a HTTP/1.1 GET request
  • Url: https://api.yes-co.com/1.0/session

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1

Response

If a valid session is available, a status ‘valid’ is returned

 string(5) "valid"

SessionUrl

  • Navigate to a page in Yes-co Open
  • This is a HTTP/1.1 GET request
  • Url: https://api.yes-co.com/1.0/session/url

Arguments

client_id (required)
Client id provided by Yes-co
user_id (required)
User id provider by Yes-co, this is an API object id
signature (required)
SHA1 encrypted version of client_id, signed with the client secret
ie.: HMAC(client_id, client_secret) ; SHA1
api_object_id (required)
Opens project/relation page
location (required)
Yes-co Open page name (currently, the only supported page name is ‘dashboard’)

Response

Url to the location/page of the API object to display

 string(42) "https://app-s03-rb2e.yes-co.com/project/3"
This page is a Wiki! Log in or register an account to edit.

Plaats een bericht