Contacts
Contacts general
The system for creating transportdocuments and digitally sharing these documents is based on contacts.
Contacts are the links in the social network that is the eWastra platform.
Your organisation can make contacts inside your environment for your customers , transporters , waste treatment facilities , waste producers , etc.
When these organizations that you have made a contact for in your environment are in fact registered on our platform as organizations the contacts in your environment can be linked to the actual organizations.
These organizations will have to register on our platform with the following link https://portal.ewastra.com , registration and use on our platform is completely free (integrating with own systems and creation of documents is not).
When these linked contacts get assigned onto a transportdocument that you create they will see these documents inside their own environment , non linked contacts will not be aware of any documents you create and assign them to.
In this article we will cover the most used contacts endpoints , for the full contact endpoint documentation you can visit our swagger reference at https://docs.xynaps.net/en/Integrations/api-reference
Contact Creation
Postman example for all properties on the contact model :
Required fields :
- ExternalId.
- Address (inside the address the streetaddress is a required field).
Name
Description
Datatype
externalId (required)
Unique external identifyer , this can be used for referring to the contact in later api calls (the internal id will be created inside our database on creation and will be given back inside the responseobject of this call).
String (max 50)
name
The name you want to give this contact , this will be the way the contact is displayed throughout the application.
String (max 200)
telephoneNumber
Telephone number for the contact.
String (max 20)
emailAddress
Emailaddress of the conctact (must be a valid email address).
String (max 320)
mobileNumber
Mobile number for the contact.
String (max 20)
faxNumber
Fax number of the contact.
String (max 20)
organizationNumber
VatNumber (this will be validated with modulo97 when regarding a Belgian companies).
String (max 15)
branchNumber
The number of the branch when dealing with multiple sites on a company (this will be validated with modulo97 when regarding a Belgian companies).
String (max 50)
license
The license to travel with waste when dealing with transporters
String (max 30)
The Adress object is in itself a required field when creating a contact, note that the streetAddress is a required field inside the Address object.
Name
Description
Datatype
Adress.Adress.externalId
Unique external identifyer , this can be used for referring to the contact in later api calls (the internal id will be created inside our database on creation and will be given back inside the responseobject of this call).
String (max 50)
Adress.streetAddress (required)
The streetname and number of the contact's address.
String (max 200)
Adress.postalCode
The postal code of the contact's address.
String (max 10)
Adress.city
The name of the city for the contact's address.
String (max 200)
Adress.country
The country name for the contact's address.
String (max 150)
Adress.countryCode
The 2 letter ISO code for the country (example for Belgium this would be BE).
String (max 2)
Adress.addionalLine
An additonal piece of information one can register regarding the contact's address
String (max 200)
Adress.latitude
The latitude coordinates of the contact's address.
long
Adress.longitude
The longitude coordinates of the contact's address.
long
The CollaborationSettings.
When sending in the collaboration settings our system will send out a connection email to the organization you wish to link this contact with.
Name
Description
DataType
CollaborationSettings.emailAddress (required)
The email address of the contact , this is the address our system will send the connection invitation to.
String (max 320)
CollaborationSettings.contactName
The name off the contact , this is will be visualised inside the email.
String (max 50)
CollaborationSettings.message
A personalized message that will be displayed inside the invitation email.
String (max 150)
The email will only be sent once per emailaddress per contact.
The Responsible Contact , this data will be displayed in the driver his app , these contact details can be used when the driver is at a location and does not see anybody on the site.
Name
Description
DataType
responsiblecontact.emailaddress
The email address of the responsible contact.
String (max 320)
responsiblecontact.mobilenumber
The mobile number of the responsible contact.
String (max 20)
responsiblecontact.name
The name of the responsible contact.
String (max 50)
responsiblecontact.telephonenumber
The telephone number of the responsible contact
String (max 20)
There is no validation on the provided contact details. What has been passed is going to be displayed.
The RegistrationNumbers are a key value pair (string ,string) that contain the registration numbers of a transporter, for example the Ovam , Brudalex , SPW numbers.
A successfull POST call will prompt a 201 Created Statuscode , the response will also include the contact object with the internal ID that has been created by our backend.
Contact retrieval
For the retrieval of the contacts inside your environment we have the following endpoints available :
Get all contacts
Performing a GET call on this endpoint will give you a list of all contacts available inside your environment. Out of the box the response will give back the first page of all your contacts with a page size of 50 , this call can be configured with pagination using the paging parameters we discussed inside this article.
Below you will find a Postman example for perfoming the GET call , we will configure the call to get the first page with a pagesize of 3
Get contact by ID
Performing a GET call on this endpoint will give back a response with the contact object of the contact that matches the id that you refer to inside the endpoint url.
This is the internal Pionira ID.
Below you will find a Postman example for perfoming the GET call :
Get contact by externalId
Performing a GET call on this endpoint will give back a response with the contact object of the contact that matches the externalId that you refer to inside the endpoint url.
Below you will find a Postman example for perfoming the GET call :
Update Contact
Invite a non linked existing contact
When you already have existing contacts in your organisation, which are not yet linked to other external users/organisations, you have the possibility to send an invite by using the Xynaps portal user interface (click on the 'connect' button of your contact) or you can send the invite by using this API call. This can be done by using the Pionira contact id or your external contact id.
Example of an API call to send the invite with Xynaps contact id: PUT {baseUrl}/api/v2/contacts/{id}/connect
For example, replacing {id} by 1234, an invite will be sent to the emailaddress of contact id 1234.
Inside the body this call is expecting the Collaboration settings object as was discussed inside the creation of a contact on top of this article.
The CollaborationSettings :
Name
Description
DataType
CollaborationSettings.emailAddress (required)
The email address of the contact , this is the address our system will send the connection invitation to.
String (max 320)
CollaborationSettings.contactName
The name off the contact , this is will be visualised inside the email.
String (max 50)
CollaborationSettings.message
A personalized message that will be displayed inside the invitation email.
String (max 150)
The email will only be sent once per emailaddress per contact.
Example based on externalId :
Example based on ID :
