API Basics Overview Addresses Sign in Create a place Create job quotes Create a job Create a package job Query a job Cancel a job Responses Standards Transport types Webhooks Policies Terms of Use Partner Policies Stuart API Using the Stuart Delivery API, developers can integrate our on-demand local delivery platform into their applications. The API is designed to allow application developers to check pricings, request a delivery, then follow updates on that delivery until completion. Important: We highly recommend that you subscribe to our API newsletter as we constantly improve our API, and are sometimes forced to make changes that are not backward compatible. subscribe to our API newsletter Basics Our API is REST based. It make use of standard HTTP verbs like GET, POST, PUT and PATCH Uses standard HTTP error responses to describe errors Authentication and authorization are based on the OAuth 2.0 standard All requests use standard query encoding All communication with our servers must be over SSL (https://) POST data should be encoded as standard application/x-www-form-urlencoded All our responses are in JSON format Accessible using https://sandbox-api.stuart.com as domain Overview To get started using the Stuart Delivery API: signup for a developer account contacting us at integrations@stuart.com or through this form if you're already a Stuart Client, and wait for an e-mail reply. It will include all the credentials you need to start. You will first use our sandbox environment. Once you are ready, request production api credentials. When the time comes, you will need a test credit card to run your tests. You can find a list of those on this page. Follow the following steps to create a delivery: Sign in to get your authorization token. Keep it in a safe place POST /v1/clients/login Refresh to get a new authorization token from a refresh token when the authorization token expires GET /oauth/v2/token Create a place (origin) where you want a package to be picked up and create a place (destination) where you want the package be delivered to POST /v1/places Create job quotes for different transport types to check the pricings POST /v1/jobs/quotes/types Create the job if you are happy with the price POST /v1/jobs Create job by package size if have a coporate account you can create a job selecting a package instead of transport type POST /v1/jobs/package Check the job status anytime by GET /v1/jobs/:jobId Optional - Provide us with a webhook URL which we will call upon Job status changes Cancel a job if you need to POST /v1/clients/:clientId/jobs/:jobId/cancel Once you are done with the integration, contact us and we will provide production credentials Addresses Correct and valid addresses are a core aspect of being able to successfully conduct deliveries at Stuart. As such, the Stuart Delivery API requires a certain level of accuracy for addresses. This section explains how you can confirm that the addresses you provide will be acceptable to the API. Requirements: We accept 2 types of addresses, both of which have slightly different requirements. Both are documented below: Precise Addresses The minimum requirements for an address to be considered precise when creating a Place are that it contains: A street number A street name A post-code A city name Approximate Addresses The minimum requirements for an address to be considered approximate when creating a Place are that it meets the following criteria: The region represented by the address has a diameter of less than 150 meters The address has a location_type as reported by Google Geocoding API as either "APPROXIMATE" or "RANGE_INTERPOLATED" If the diameter of the address region is between 20 and 150 meters, a contactPhone is required (when creating a Place) If you want to confirm your addresses are acceptable yourself you may do so as follows: Use Google's Geocoding API to geocode your address Confirm that the response from Google for each address includes at least one address_components entry of type "street_number" and a location_type value of "ROOFTOP", "APPROXIMATE" or "RANGE_INTERPOLATED" If the result has a bounds field then the diameter of a circle filling the area must be less than 150 meters Addresses that do not meet these criterias will be rejected when creating a Place, in most cases, the response will include a list of alternatives you can use. Additionally if you have a large number of addresses you believe may not be valid please contact us. In some cases we may be able to provide a paid service that will validate your addresses and provide you with suggestions for invalid addresses. Sign in In the email we sent to you, you should have all credentials required. Now you should be able to log in as a client and get your OAUTH2 Token. Please note this endpoint will change within weeks, please subscribe to our API newsletter to be alerted when it happens. The change will be minimal. POST https://sandbox-api.stuart.com/v1/clients/login POST Parameters Name Description username Mandatory API User Name (your e-mail) password Mandatory Password that you've chosen (you should've set it by clicking a link on the email) grant_type Mandatory Value must be password URL (GET) Parameters Name Description client_id Mandatory API Client ID we sent you in the email client_secret Mandatory API Client Secret we sent you in the email response_type Mandatory Value must be code scope Mandatory Value must be api CURL POSTMAN curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d 'username=USERNAME&password=PASSWORD&grant_type=password' "https://sandbox-api.stuart.com/v1/clients/login?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&response_type=code&scope=api" The response will return your client basic information and the client access token { "id": 1234, "firstname": "John", "lastname": "Smith", "lastnameInitial": "S.", "phone": "+34611111111", "refreshToken": "REFRESH_TOKEN", "token": "ACCESS_TOKEN" } The access token must be sent from now on, to identify yourself. Must be included in the HTTP request headers, as following: GET https://sandbox-api.stuart.com/some_endpoint HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Host: sandbox-api.stuart.com Refreshing the token When the token you got from the login expires you will get a (401 Unauthorized) response from any endpoint where you're using the expired token. The answer will have this shape: { "error": "invalid_grant", "error_description": "The access token provided has expired." } In this case you can use the REFRESH TOKEN you got on the /v1/clients/login call to get a new valid token. To request a new valid token from a valid REFRESH TOKEN you must use the following endpoint: GET https://sandbox-api.stuart.com/oauth/v2/token URL (GET) Parameters Name Description client_id Mandatory API Client ID we sent you in the email client_secret Mandatory API Client Secret we sent you in the email grant_type Mandatory Value must be refresh_token refresh_token Mandatory Refresh token provided on /v1/clients/login call CURL curl -X GET "https://sandbox-api.stuart.com/oauth/v2/token?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN" The response will give you a new valid token and also a new valid refresh token { "access_token": "NEW_ACCESS_TOKEN", "expires_in": TOKEN_EXPIRATION_IN_SECONDS (right now the default value is 172800), "token_type": "bearer", "scope": "api", "refresh_token": "NEW_REFRESH_TOKEN" } The new access token must be sent from now on, to identify yourself. Must be included in the HTTP request headers, as following: GET https://sandbox-api.stuart.com/some_endpoint HTTP/1.1 Authorization: Bearer ACCESS_TOKEN Host: sandbox-api.stuart.com Places Two places must be created. One for pickup address and one for delivery address. POST https://sandbox-api.stuart.com/v1/places POST Parameters Name Description placeTypeId Mandatory 2 for picking, 3 for delivering addressStreet Optional, recommended Place position (Google maps style string). addressPostcode Optional, recommended Place Postcode (used with addressStreet). contactPhone Optional, recommended. Possibly mandatory; see note below. Contact Phone number for driver to contact if required. This may be an international format, or a local format. When a local format is provided it is converted to an international format using the associated address' country code. contactFirstname Optional Contact first name. contactLastname Optional Contact last name. contactCompany Optional Contact company. contactEmail Optional Contact Email address geoPlaceId Optional Google Place ID addressLatitude Deprecated Latitude of the address addressLongitude Deprecated Longitude of the address Important: Either geoPlaceId, addressStreet and/or addressPostcode may be used to successfully create a place. On occasion when the address provided is not sufficiently precise a 422 response may be encountered requiring the presence of a valid contactPhone value. This is required to assure the Driver's ability to reach the address. CURL curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -d 'addressLatitude=ADDRESS_LATITUDE&addressLongitude=ADDRESS_LONGITUDE&placeTypeId=PLACE_TYPE' "https://sandbox-api.stuart.com/v1/places" The server will then try to create a place using the address provided. { "id": 356697, "name": "", "contactFirstname": "", "contactLastname": "", "contactCompany": "", "contactPhone": null, "contactEmail": "", "comment": null, "createdAt": "2016-05-08T12:13:22+0000", "placeType": { "id": 2, "name": "Picking", "code": "picking" }, "address": { "id": 375953, "street": "Rambla de Volart 43, Barcelona", "postcode": "08041", "latitude": 41.416667, "longitude": 2.177082, "city": { "id": 3, "name": "Barcelona", "code": "barcelona", "timezone": "Europe/Madrid", "latitude": 41.39479, "longitude": 2.1487679, "region": { "id": 61, "name": "Barcelona", "country": { "id": 3, "name": "Spain", "iso2Code": "ES", "defaultCurrency": { "rate": 1, "name": "Euro Member Countries, Euro", "isoCode": "EUR", "symbol": "€" } } } } } } However, an error may occur at this time, you should try to handle it and act accordingly. In case the provided address is somewhere Stuart does not work yet: { "errors": [{ "code": 400004, "message": "This location is out of range", "key": "OUT_OF_RANGE" }] } Job quotes Now that you have a pickup place and a delivery place, you can query for the pricings for the different transport types that Stuart can handle. JobQuotes are only valid a few minutes and shouldn't be stored longer. POST https://sandbox-api.stuart.com/v1/jobs/quotes/types POST Parameters Name Description transportTypeIds Mandatory Which transport types you want to get the quotes for, comma-separated. For instance: 1 (walker) 2 (bike) 3 (motorbike) 4 (car) 5 (cargobike) 6 (van) originPlaceId Mandatory (either originPlaceId or origin, origin have the preference), soon deprecated Pickup Place ID retrieved using Places endpoint origin Mandatory (either originPlaceId or origin, origin have the preference) String that fully identifies the picking address (by ex. "Rambla de Volart 43, Barcelona") originContactPhone Optional, recommended. Possibly mandatory; see note below. Pickup contact phone number for driver to contact if required. This may be an international format, or a local format. When a local format is provided it is converted to an international format using the associated address' country code. originContactFirstname Optional Origin contact first name. originContactLastname Optional Origin contact last name. originContactCompany Optional Origin contact company. originContactEmail Optional Contact Email address destinationPlaceId Mandatory (either destinationPlaceId or destination, destination have the preference), soon deprecated Delivery Place ID retrieved using Places endpoint destination Mandatory (either destinationPlaceId or destination, destination have the preference) String that fully identifies the delivery address (by ex. "Carrer de Sardenya, 339") destinationContactPhone Optional, recommended. Possibly mandatory; see note below. Destination contact phone number for driver to contact if required. This may be an international format, or a local format. When a local format is provided it is converted to an international format using the associated address' country code. destinationContactFirstname destinationContactLastname Optional Destination contact last name. destinationContactCompany Optional Destination contact company. destinationContactEmail Optional Contact Email address clientId Mandatory, soon deprecated Your own client ID (Retrieved through login process) Important: On occasion when the address provided is not sufficiently precise a 422 response may be encountered requiring the presence of a valid contactPhone value. This is required to assure the Driver's ability to reach the address. CURL curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -d 'transportTypeIds=1,2,3,4,5&originPlaceId=ORIGIN_PLACE_ID&destinationPlaceId=DESTINATION_PLACE_ID' "https://sandbox-api.stuart.com/v1/jobs/quotes/types" If you choose to use the recommended way to call this endpoint (sending origin and destination instead of originPlaceId and destinationPlaceId) this endpoint will create an origin place and a destination place internally, so you should not use the /v1/places call to create the places. The server will return an object with several Job Quotes, one for every transport type requested. Every field name matches the transport type ID requested { "1": { "errors": { "code": 9999, "message": "CustomException thrown JOB_DISTANCE_NOT_ALLOWED", "key": "JOB_DISTANCE_NOT_ALLOWED" } }, "2": { "id": 730068, "distance": 1.765, "duration": 5, "durationWithTraffic": 5, "polyline": "eex{FwehLo@nCTN|FrDnBwCnBwCbCeDvDpF|EhHtBvCdHATAHMJOP@zGILRhDxEdJ|MbAyA", "originalTotalAmount": 6, "finalTotalAmount": 6, "cancellationPrice": 6, "minPrice": 0, "basePrice": 0, "expireAt": "2016-05-08T12:22:58+0000", "originPlace": { "id": 356697, "name": "", "contactFirstname": "", "contactLastname": "", "contactCompany": "", "contactPhone": null, "contactEmail": "", "comment": null, "createdAt": "2016-05-08T12:13:22+0000", "placeType": { "id": 2, "name": "Picking", "code": "picking" }, "address": { "id": 375953, "street": "Rambla de Volart 43, Barcelona", "postcode": "08041", "latitude": 41.416667, "longitude": 2.177082, "city": { "id": 3, "name": "Barcelona", "code": "barcelona", "timezone": "Europe/Madrid", "latitude": 41.39479, "longitude": 2.1487679, "region": { "id": 61, "name": "Barcelona", "country": { "id": 3, "name": "Spain", "iso2Code": "ES", "defaultCurrency": { "rate": 1, "name": "Euro Member Countries, Euro", "isoCode": "EUR", "symbol": "€" } } } } } }, "destinationPlace": { "id": 356698, "name": "", "contactFirstname": "", "contactLastname": "", "contactCompany": "", "contactPhone": null, "contactEmail": "", "comment": null, "createdAt": "2016-05-08T12:13:25+0000", "placeType": { "id": 3, "name": "Delivering", "code": "delivering" }, "address": { "id": 375954, "street": "Carrer de Sardenya, 339", "postcode": "08025", "latitude": 41.404849, "longitude": 2.171311, "city": { "id": 3, "name": "Barcelona", "code": "barcelona", "timezone": "Europe/Madrid", "latitude": 41.39479, "longitude": 2.1487679, "region": { "id": 61, "name": "Barcelona", "country": { "id": 3, "name": "Spain", "iso2Code": "ES", "defaultCurrency": { "rate": 1, "name": "Euro Member Countries, Euro", "isoCode": "EUR", "symbol": "€" } } } } } }, "currency": { "rate": 1, "name": "Euro Member Countries, Euro", "isoCode": "EUR", "symbol": "€" }, "discount": null, "coupon": null, "pricePerKm": 0, "pricePerMin": 0, "job_type_code": "job_quote_transport_standard" }, ... Keep the job quote ID as you'll need it to create a job with it. As you can see, in this example we got an error creating the job_quote for transport type 1 (walk). In this case we are trying to create a job quote for a transport type and the distance allowed for the transport type has been exceeded. Create a Job By sending a job quote, you will be able to create a job. At this time, you can also set some comments for the courier, for pickup and delivery. For instance, "Ring the bell on arrival". You can also set a picture of the package. They'll really appreciate it! POST https://sandbox-api.stuart.com/v1/jobs POST Parameters Name Description jobQuoteId Mandatory Job Quote ID (Note: By selecting a jobQuoteId you're also selecting the transport type) comment Optional A comment about the job content. originComment Optional A comment for the courier to help him pickup the package; floor number, door, etc. destinationComment Optional A comment for the courier to help him deliver the package; floor number, door, etc. photo Optional A picture of the package, base64 encoded. clientReference Optional A string that allows to you uniquely identify the job. We do not allow the creation of a job when there is another active job with the same client reference. CURL curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -d 'jobQuoteId=JOB_QUOTE_ID' "https://sandbox-api.stuart.com/v1/jobs" { "id": 13173, "comment": null, "lastStatus": { "id": 33087, "jobStatusType": { "id": 1, "code": "new" }, "status": "new" }, "currentDelivery": null, "transportType": { "id": 1, "code": "walk" }, "packageType": null, "status": "new" } Keep in mind that when you're creating a job you can also get some different errors from our API: { "errors": [ { "code": 400428, "message": "job quote already exist. Duplicate job", "key": "JOB_QUOTE_ALREADY_EXIST" } ] } You can only use JobQuote once per job, that error will be shown when you're trying to re-use the jobQuote to create a new Job. If you want to re-use the places (origin and/or destination) you can do it but you should always create a new JobQuote every time you want to create a Job. Create a job by package An alternative way to create a job in a single call selecting origin, destination and package size. POST https://sandbox-api.stuart.com/v1/jobs/package POST Parameters Name Description packageTypeId Mandatory Which package size you want to send. 1 (small) 2 (medium) 3 (large) 4 (extra large) clientReference Optional A string that allows to you uniquely identify the job. We do not allow the creation of a job when there is another active job with the same client reference. comment Optional A comment about the job content. originAddressStreet Mandatory String that fully identifies the picking address (by ex. "Rambla de Volart 43, Barcelona") originComment Optional A comment for the courier to help him pickup the package; floor number, door, etc. originContactPhone Optional, recommended. Possibly mandatory; see note below. Pickup contact phone number for driver to contact if required. This may be an international format, or a local format. When a local format is provided it is converted to an international format using the associated address' country code. originContactEmail Optional Pickup contact email. originContactName Optional Pickup contact name. destinationAddressStreet Mandatory String that fully identifies the delivery address (by ex. "Carrer de Sardenya, 339") destinationComment Optional A comment for the courier to help him deliver the package; floor number, door, etc. destinationContactPhone Optional, recommended. Possibly mandatory; see note below. Destination contact phone number for driver to contact if required. This may be an international format, or a local format. When a local format is provided it is converted to an international format using the associated address' country code. destinationContactEmail Optional Pickup contact email. destinationContactName Optional Pickup contact name. Important: On occasion when the address provided is not sufficiently precise a 422 response may be encountered requiring the presence of a valid contactPhone value. This is required to assure the Driver's ability to reach the address. CURL curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" -d 'packageTypeId=2&clientReference=a45frg7&originAddressStreet=Rambla de Volart 43, Barcelona, Barcelona&originContactPhone=+34654768767&destinationAddressStreet=Carrer de Sardenya, 339, Barcelona&originComment=6 floor&destinationComment=Ask for John Doe&comment=A little box' "https://sandbox-api.stuart.com/v1/jobs/package" { "id": 13173, "comment": "A little box", "lastStatus": { "id": 33087, "jobStatusType": { "id": 1, "code": "new" }, "status": "new" }, "clientReference": "a45frg7", "originPlace": { ... }, "destinationPlace": { ... }, "currentDelivery": null, "transportType": null, "packageType": { "id": 2, "name": "Medium", "code": "medium", "defaultMaxRadius": 2 }, "status": "new" } Keep in mind that when you're creating a job by package, the price can vary depending on the final driver delivering it Query for a Job You can check the job status at any time, but we highly recommend using webhooks if you can implement them for real-time updates. GET https://sandbox-api.stuart.com/v1/jobs/:jobId URL (GET) Parameters Name Description jobId The Job ID you want to check CURL curl -X GET -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/x-www-form-urlencoded" "https://sandbox-api.stuart.com/v1/jobs/JOB_ID" { "id": 13171, "expirationInterval": 300, "expiresAt": "2016-05-01T09:53:53+0000", "comment": null, "originComment": "holaaaa", "destinationComment": "adeuuu", "lastStatus": { "id": 33083, "jobStatusType": { "id": 4, "code": "finished", "name": "finished" }, "status": "finished" }, "renewable": 0, "createdAt": "2016-05-01T09:48:53+0000", "updatedAt": "2016-05-01T09:49:25+0000", "currentDelivery": { "id": 5626, "estimatedDistanceToOrigin": 668, "estimatedDistanceToDestination": 0, "etaToDestination": "2016-05-01T09:49:23+0000", "etaToOrigin": "2016-05-01T09:49:00+0000", "traveledToOriginDistance": 0.798987, "lastDeliveryStatus": { "id": 23241, "deliveryStatusType": { "id": 3, "code": "delivered" }, "status": "delivered" }, "driver": { "id": 2631, "firstname": "478f014", "lastnameInitial": "4.", "phone": "+33999999999", "ratingAvg": 5 }, "transportType": { "id": 1, "code": "walk" }, "status": "delivered" }, "client": { "id": 2640, "firstname": "Sergi", "lastnameInitial": "I.", "phone": "+34677722821", "picturePath": "", "ratingAvg": 1.667, }, "finalJobPrice": { "finalTotalAmount": 6, "taxPercentage": 2100, "id": 23332, "jobQuote": { "id": 95480, "finalTotalAmount": 6, "expireAt": "2016-05-01T09:50:16+0000" } }, "picturePath": null, "status": "finished" } Note that a job can have different status, as the lifecycle is as follows: new We've accepted the job and will be assigning it to a driver. in_progress Driver has accepted the job and started the delivery. When the job is in_progress we can look at delivery statuses to track the progress in the currentDelivery object: picking The driver is in route to pick up the package. almost_picking The driver is close to the picking point. delivering The driver has picked the package and is in route to deliver it. almost_delivering The driver is close to the delivering point. delivered The package has been delivered successfully. cancelled The delivery was cancelled. finished The package was delivered successfully. canceled The package won't be delivered as it was cancelled by the client. Please note this is canceled and not cancelled. We will fix those in an API update so you should probably check for both. expired Job has expired. No driver accepted the job. It didn't cost any money. Cancel a Job A job can be cancelled without a fee before it's accepted by a driver or within the two first minutes if the driver has not picked yet the package. POST https://sandbox-api.stuart.com/v1/clients/:clientId/jobs/:jobId/cancel CURL curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" "https://sandbox-api.stuart.com/v1/clients/CLIENT_ID/jobs/JOB_ID/cancel" The server will return a response if cancellation was handled properly. { "success":true } If the job is not cancellable (Driver already picked up the package, for example), you'll receive an error: { "errors": [{ "code": 400432, "message": "The job is not cancelable", "key": "JOB_NOT_ALLOW_TO_CANCEL" }] } And that's it! If you have any doubts, or you need some support, don't hesitate to contact us integrations@stuart.com Happy delivering! Responses The Stuart API uses HTTP status codes to indicate the status of your requests. This includes successful and unsuccessful responses. Responses will also include JSON formatted details for further details. 200 - OK: Everything went as planned. 201 - Created. 204 - OK but no content 304 - Not Modified: Resource hasn't been updated since the date provided. 400 - Bad Request: You did something wrong. Often a missing argument or parameter. 401 - Unauthorized: Authentication was incorrect. 403 - Forbidden: You don't have the necessary permissions for the resource. 404 - Not Found 422 - We couldn't process your request. Check the response message 500 - Internal Server Error: We had a problem processing the request. 503 - Service Unavailable: Try again later. Errors Error responses include details about what went wrong. Error format { "errors": [{ "code": ERROR_CODE, "message": MESSAGE, "key": ERROR_KEY }] } The complete list of error keys and codes: code key message 404001 The job cannot be found The job cannot be found 404021 Client not found Client not found 404023 Address not found Address not found 404022 City not found City not found 422007 Email is not correct Email is not correct 422002 Phone is not correct Phone is not correct 422003 Password is not correct Password is not correct 404017 Device not found Device not found 404003 Rating not found Rating not found 404019 Credit card not found Credit card not found 404002 Transport type not found Transport type not found 422006 Latitude is not correct Latitude is not correct 422005 Longitude is not correct Longitude is not correct 404016 Driver device location not found Driver device location not found 404015 Driver status not found Driver status not found 404013 Incident not found Incident not found 404012 Incident type not found Incident type not found 404014 Incident creator type not found Incident creator type not found 422004 Origin place not found Origin place not found 404018 Destination place not found Destination place not found 404020 Coupon code not found Coupon code not found 404007 Job type not found Job type not found 404008 Job quote not found Job quote not found 404009 Job invitation not found Job invitation not found 422021 Error accepting job invitation Error accepting job invitation 404006 Place not found Place not found 404005 Place type not found Place type not found 422001 Place is not correct Place is not correct 422001 Address is not specific enough Address is not specific enough 404004 Pricing method not found Pricing method not found 400001 The given device is not property of the given client The given device is not property of the given client 400002 The given job is not property of the given client The given job is not property of the given client 500000 The payment was declined The payment was declined 422008 No drivers available for this job No drivers available for this job 422009 The new status provided is already set for the job The new status provided is already set for the job 404024 The password is not correct The password is not correct 404025 The email is not correct The email is not correct 400003 Job type is not correct Job type is not correct 403001 Permission denied Permission denied 400004 This location is out of range This location is out of range 400005 The driver is busy. Cannot change status. The driver is busy. Cannot change status. 400006 Client email exists Client email exists 400007 Client phone exists Client phone exists 400008 Job invitation not available Job invitation not available 400009 Payment platform error Payment platform error 400010 Geocoding error Geocoding error 422010 City is not correct City is not correct 404011 Delivery not found Delivery not found 404026 Incident status type not found Incident status type not found 404027 Username not found Username not found 400011 Set delivery status picked error Set delivery status picked error 400012 Set delivery status deliverederror Set delivery status deliverederror 400013 Driver device error Driver device error 400014 Job quote error Job quote error 400015 Job picked not available Job picked not available 400016 Job delivered not available Job delivered not available 400017 Billing account error Billing account error 400018 Platform transaction error Platform transaction error 400020 Set delivery travel error Set delivery travel error 400019 The job cannot be accepted. The driver is busy. The job cannot be accepted. The driver is busy. 400021 Verification code error Verification code error 400022 Job Distance not allowed Job Distance not allowed 400023 Job time not allowed Job time not allowed 400024 Status Driver cannot change to same status Status Driver cannot change to same status 400025 Job Type Not Available Job Type Not Available 400026 Coupon not available for this job Coupon not available for this job 400027 Route not valid Route not valid 400427 Client updating error Client updating error 400428 job quote already exist. Duplicate job job quote already exist. Duplicate job 400429 Driver email exist Driver email exist 400430 Driver phone exist Driver phone exist 404028 Referrer do not exist Referrer do not exist 400431 Driver invitation accept error. Same driver Driver invitation accept error. Same driver 400432 The job is not cancelable The job is not cancelable 400027 Time granularity provided is not valid. Time granularity provided is not valid. 400028 Date range required for this API call. Date range required for this API call. 400029 Date format provided is not valid (YYYY-MM-DD). Date format provided is not valid (YYYY-MM-DD). 400030 Date must be provided. Date must be provided. 400031 Job is not evaluable. Job is not evaluable. 400032 Status Change not allowed. Status Change not allowed. 404029 Referrer do not exist (soft check) Referrer do not exist (soft check) 400103 Cannot register device Cannot register device 400101 Job quotes not available Job quotes not available 400102 Job quotes not available Job quotes not available 400104 Duplicate Job Duplicate Job 400108 Incompatible currencies on this transaction Incompatible currencies on this transaction 400107 Credit card is not property of client Credit card is not property of client 400109 Error getting client Error getting client 400110 Incorrect Bounding Box Incorrect Bounding Box 422011 The job must be delivering to be able to be returned The job must be delivering to be able to be returned 422012 Client can´t use driver referrals Client can´t use driver referrals 422013 Driver can´t use client referrals Driver can´t use client referrals 500001 The notification cannot be logged The notification cannot be logged 400433 The SMS can't be sent The SMS can't be sent 422014 The job invitation has expired The job invitation has expired 422015 The job invitaiton has been accepted by another driver The job invitaiton has been accepted by another driver 422016 The job has been canceled The job has been canceled 422018 Driver can´t use salesman referrals Driver can´t use salesman referrals 422017 The credit card is associated to a running job The credit card is associated to a running job 422019 The job is not returning The job is not returning 422020 Job invitation already accepted Job invitation already accepted 404030 Drive not found Drive not found 400136 This user have no access to this resource This user have no access to this resource 400135 This user can´t update to this resource This user can´t update to this resource 401001 The access token provided is invalid. The access token provided is invalid. 404031 App not found App not found 500001 Unknown Error Unknown Error Standards Currency When a response involves a currency, it is described as follows: { finalTotalAmount: 5.90, currency: { isoCode: "EUR", symbol: "€" } } This indicates a value of €5.90 in EUR. VAT and other percentages Percentage values are always represented as integers, and should be divided by 100 to have the right value. Eg. 2100 corresponds to 21% Eg. 1850 corresponds to 18.5% Times Times are formatted according to ISO8601 ( YYYY-MM-DDThh:mm:ssTZD ) and reported only in UTC time. For example: { createdAt: "2015-08-09T09:31:09+0000", } Objects will often have attributes like "createdAt" and "updatedAt". Locations Some objects have a geographic location associated with them. This typically of the form: { "address" : { "street": "29 Rue Desaix" "latitude" : 48.85184097, "longitude" : 2.2921195 } } Transport types Stuart handles different transport types, depending on the city. Check the table below to understand which transport types are available per city Paris Barcelona London ID Name Details 2 Bike 3 Motorbike 4 Car Webhooks If you want to receive real-time updates for the job statuses, you should implement a HTTP webhook and set the URL in your API settings (Sandbox, Production) to enable it. We will send a JSON payload to the endpoint for every job status update, you can read more about the possible statuses. We will send the JSON as body and it includes the following information. { "id": 1, "currentDelivery": { "id": 1, "driver": { "status": "busy", "latitude": "72.95559451", "longitude": "-155.95014084" }, "status": "delivered" // Can be cancelled delivered delivering almost_delivering picking almost_picking }, "transportType": { "code": "walk" // Can be walk bike motorbike cargobike car }, "status": "finished" // Can be expired canceled finished in_progress accepted new } Stuart API Terms Of Use Stuart SAS (“Stuart” or “we”) operates an on-demand delivery platform through our applications and websites (the “Stuart Service”) to power on-demand delivery of goods in our cities. We have developed an application programming interface (the “Stuart API”) and other technical documentation and materials (the “API Materials”) to allow you to develop your own websites or applications that can be used with the Stuart API to fulfill deliveries for your own services and products (an “Application”). Introduction Use of the Stuart API and the Stuart Service is governed by and subject to these Terms of Use (the “API Terms”), and the API Terms constitute a legal agreement by and between you ( “Partner” or “you”) and Stuart (each a “Party” and together as the “Parties”). Stuart reserves the right to modify these API Terms at any time without prior notification, so please review this page periodically for changes. You must agree upon and abide by these changes accordingly, and any use of the Stuart API and Stuart Service at any time constitutes full acceptance of the API Terms. In consideration of the mutual promises, covenants and agreements contained herein, and other good and valuable consideration, the receipt, sufficiency and adequacy of which are hereby acknowledged, the Parties, intending to be legally bound, agree to the foregoing and as follows: API License API License from Stuart. Subject to these API Terms, Stuart hereby grants you a limited, non-exclusive, non-sublicensable and non-transferable license to access and use the Stuart API in accordance with the API Materials and to use the API Materials, in each case, solely for the purposes of: (i) developing and testing the application and websites for use with the Stuart API; (ii) obtaining data made available by Stuart through the Stuart API (“Stuart Data”) for use by you in accordance with this Agreement; and (iii) providing data to Stuart through the API (“Partner Data” and together with Stuart Data, “Data”) for use by Stuart in accordance with this Agreement. License Restrictions. You will not and will not allow any of your directors, officers, employees, agents or contractors (collectively, “Personnel”) to: (i) reverse engineer, disassemble, decompile or otherwise attempt to derive the source code or the underlying ideas, algorithms, structure or organization of the Stuart API or any Stuart Service, or any part of any of the foregoing; (ii) sublicense, transfer, distribute or otherwise make available the Stuart API or any API Materials or Stuart Service, or any part of any of the foregoing, in any form; (iii) lease, loan or sell the Stuart API or any API Materials or the Stuart Service, or any part of the foregoing; (iv) create derivative works of or otherwise modify the Stuart API or any API Materials or Stuart Service, or any part of any of the foregoing; (v) make any copies of the Stuart API or any API Materials, or any part of any of the foregoing, in any form; or (vi) attempt to defeat, avoid, bypass, remove, deactivate or otherwise circumvent any software protection mechanisms in the Stuart API or any Stuart Service, including without limitation, any such mechanism used to restrict or control the functionality of any of the foregoing. Reservation of Rights. Stuart does not grant you any rights in or to the Stuart API, API Materials and Stuart Service except as expressly set forth in Section 2(a) above, and as between the Parties, Stuart owns and retains ownership of the Stuart API, API Materials and Stuart Service, including any and all rights under patent law, copyright law, trade secret law, trademark law and any and all other proprietary rights ( “Intellectual Property Rights”). Data Partner Data. Subject to the terms and conditions of the API Terms you hereby grant Stuart and its contractors a non-exclusive, non-sublicensable and non-transferable worldwide right to use the Partner Data (i) in connection with providing the Stuart Service in accordance with the API Terms; and (ii) to understand and analyze the usage trends and preferences of users to improve the Stuart Service, and to develop new products, services, feature, and functionality. Stuart Data. Subject to the terms and conditions of the API Terms, Stuart hereby grants you a non-exclusive, non-sublicensable and non-transferable worldwide right to use the Stuart Data solely as necessary to fulfil its customer orders and for internal business purposes. Reservation of Rights. As between Stuart and you, Stuart retains the sole and exclusive title in and to all Stuart Data, and you retain the sole and exclusive title in and to all Partner Data. Data Protection. Stuart will not use the Partner Data for any purposes other than as expressly permitted in Section 3(a). You will not use the Stuart Data for any purposes other than as expressly permitted in Section (3)(b). Except as expressly set forth in this Section 3, each Party shall not make available, display, disclose, transfer, sell, rent, or lease any of the other Party’s Data, without the other Party’s express written consent. When you collect data from or regarding individuals or their devices, and such data constitutes part of the Data (“User Data”), you shall obtain each applicable individual’s prior permission for the collection of the User Data, as well as the use and sharing of such User Data pursuant to the provisions of this Agreement. You shall have in place a privacy policy that accurately and completely describes the collection, use, and sharing of Partner’s User Data and the purposes for which the User Data is collected, used and shared. Without limiting your obligation in Section 3(d)(ii), the privacy policy must be prominently identified or located where users download and access Partner’s product or service that collects the User Data. In addition, you shall comply with any applicable laws and regulations in connection with the User Data, including personal data protection and privacy laws and regulations. Each Party shall implement reasonable security measures to safeguard the other Party’s Data. Each Party reserves the right to require the other Party to delete the first Party’s Data if the other Party violates the API Terms. Parties' Obligation Partner Obligations. You agree to perform the obligations as set forth in the Partner Policies and Rules of Conduct, which are incorporated into these API Terms. Mutual Obligations. Each Party agrees: not to perform any action with the intent of introducing to the other Party’s systems, products or services any viruses, worms, defects, Trojan horses, malware or any items of a destructive nature. in connection with its performance of the API Terms, not to defame, abuse, harass, stalk or threaten others or promote or facilitate unlawful online gambling or disruptive commercial messages or advertisements. to conduct business in a manner that does not reflect negatively on the other Party and its products and services. not to make any statement that suggests partnership with, sponsorship by or endorsement by the other Party without the other Party’s prior written approval. not to use web scraping, web harvesting, or web data extraction methods to extract data from the other Party. Fees and Payment Fees and Payment Terms. You will pay Stuart fees for the Stuart Service in accordance with API Pricing Policy, which is incorporated in these API Terms Taxes. You will be responsible for and to pay, or to reimburse Stuart on written request, if Stuart is required to pay or collect, any sales, use, VAT, excise, export or other tax, duty or other charge of any kind or nature (excluding any tax that is based on Stuart’s net income) that is levied or imposed by any governmental authority on the use of the Stuart Service or any portion thereof. Confidential Information “Confidential Information” shall mean any information relating to or disclosed in connection with the API Terms and the use of the Stuart API, which is or should be reasonably understood to be confidential or proprietary to Stuart, including, but not limited to, technical processes and formulas, source code, product designs, sales, cost and other unpublished financial information, product and business plans, projections, and marketing data. Non-Use and Non-Disclosure. You agree that, unless Stuart gives its prior written authorization, you shall: (a) not use the Confidential Information for any other purpose other than for use of the Stuart API and Stuart Service; or (b) not disclose any such Confidential Information to any person or entity except your directors, officers, employees and contractors who are required to have such Confidential Information in order to implement and use the Stuart API and Stuart Service and who are bound by confidentiality obligations protecting the Confidential Information similar to the provisions hereof. Maintenance of Confidentiality. You shall prevent the unauthorized access, use, disclosure, dissemination or publication of the Confidential Information with the same degree of care that you use to protect your own confidential information of a similar nature, but no less than a reasonable degree of care. You agree to notify Stuart in writing of any misuse or misappropriation of the Confidential Information which may come to your attention. Compelled Disclosure. If you become legally obligated to disclose Confidential Information by any governmental entity with jurisdiction over it, to the extent permitted by law, youshall give Stuart prompt written notice of such obligations sufficient to allow Stuart the opportunity to pursue its legal and equitable remedies (including but not limited to making an application for a protective order) regarding such potential disclosure. You agree to: (a) assert the confidential nature of such Confidential Information to the governmental entities; (b) disclose only such Confidential Information as is required to be disclosed by law; (c) use its commercially reasonable efforts to obtain confidential treatment for any such Confidential Information that is so disclosed; and (d) provide reasonable assistance to Stuart in protecting such disclosure. Return of Materials. All documents and other tangible objects containing or representing Confidential Information that have been disclosed by Stuart, and all copies or extracts thereof or notes derived therefrom that are in your possession, shall be and remain the property of Stuart and shall be promptly returned to Stuart or destroyed (with proof of such destruction), each upon Stuart written request. Term and Termination You may terminate these API Terms at any time by ceasing all use of the Stuart API and API Materials and deleting all copies of the Stuart API Materials (including all Stuart Data) in your possession or control. We may immediately revoke your use of the Stuart API without notice if that use violates any of these API Terms or if we otherwise object to your use of the Stuart API. We may also terminate any rights granted hereunder, or may add or remove functionalities or features of the Stuart API, at any time and for any reason at our discretion. We will not be liable to you or any third party for any costs or damages as a result of termination of this agreement. Sections 1, 2(b), 2(c), 3(c), 3(d), 4(a), 5(b), 6, 7(a), 8, 9(b), 10, and 11 shall survive any termination or expiration of this Agreement. Indemnification Partner Indemnity. You shall defend Stuart, its subsidiaries, affiliates, officers, directors and employees (“Stuart Indemnified Parties”), individually and collectively, against or at your discretion, settle any claims, suits, actions or proceedings (“Claims”) brought against the Stuart Indemnified Parties by a third party to the extent arising from: (i) your use of the Stuart API, API Materials, Stuart Data or Stuart Service except as expressly allowed by the API Terms; or (ii) your breach of Section 3(d) (Data Protection); or (iii) any claim that the Application, or any part thereof, infringes any third party Intellectual Property Rights. You shall pay any settlement amounts agreed by you or damages finally awarded to such third party in such Claims. Procedure. You shall provide Stuart: (i) prompt written notice of any Claim subject to your indemnification obligation, (ii) exclusive control over the defense and settlement of such Claim, and (iii) at your sole expense, proper and full information and assistance to settle or defend any such Claim. No settlement of such Claim that involves a remedy other than the payment of money by you shall be entered into without the written consent of Stuart. Warranties and Disclaimer Warranties. Each Party represents and warrants to the other Party that: (i) it has the necessary corporate power and authority to enter into and perform this agreement; (ii) it will comply with all applicable laws, rules and regulations (including without limitation data protection and privacy laws and regulations) in the exercise of its rights and obligations under this agreement; and (iii) it will make no false or misleading representations with respect to the other Party or its products or services. DISCLAIMER. THE STUART API, API MATERIALS, STUART DATA AND STUART SERVICE, ALONG WITH OTHER MATERIALS PROVIDED BY STUART IN CONNECTION WITH THIS AGREEMENT ARE PROVIDED ON AN “AS IS” AND “AS AVAILABLE” BASIS. EXCEPT AS EXPRESSLY PROVIDED IN SECTION 9(A) ABOVE, STUART, ON BEHALF OF ITSELF AND ITS SUPPLIERS, disclaims all warranties and conditions of any kind, whether express, implied or statutory, including, but not limited to, the implied warranties and conditions of merchantability, fitness for a particular purpose and non-infringement. Neither Stuart nor any of its licensors guarantees the availability, accuracy, completeness, reliability, or timeliness of any data or information AVAILABLE THROUGH THE API OR API MATERIALS. Product Damage or Lost Product. Stuart will pay you the out-of-pocket expense that you incur for replacement or repair, at Stuart’s discretion, of each item to be delivered by Stuart that is lost or damaged while in the possession of or under the control of Stuart or any third-party engaged by Stuart to perform the Stuart Service, or due to any performance or failure to perform such Stuart Services. Notwithstanding the foregoing, in no case shall Stuart pay more than $100.00 per delivery pursuant to this provision, and the burden of proving the applicability of this provision rests upon you. Exclusions. Stuart will not be liable for any loss or damage to the extent such loss or damage results from an act or omission of you, one of your vendors, employees, contractors, agents, customers, or any business invitee on your premises. Limitation of Liability EXCEPT FOR A BREACH OF SECTION 6 (CONFIDENTIAL INFORMATION) AND AMOUNTS PAYABLE TO THIRD PARTIES UNDER SECTION 8 (INDEMNIFICATION), EACH PARTY WILL NOT, UNDER ANY CIRCUMSTANCES, BE LIABLE TO THE OTHER PARTY FOR CONSEQUENTIAL, INCIDENTAL, SPECIAL, OR EXEMPLARY DAMAGES ARISING OUT OF OR RELATED TO THE TRANSACTION CONTEMPLATED UNDER THIS AGREEMENT, INCLUDING BUT NOT LIMITED TO LOST PROFITS OR LOSS OF BUSINESS, EVEN IF THE PARTY IS APPRISED OF THE LIKELIHOOD OF SUCH DAMAGES OCCURRING. IN NO EVENT SHALL STUART’S TOTAL LIABILITY TO YOU UNDER THIS AGREEMENT FOR ALL DAMAGES EXCEED THE AMOUNT OF FEES PAID BY YOU IN THE TWELVE-MONTH PERIOD IMMEDIATELY PRECEDING THE OCCURANCE OF THE CLAIM. NO STUART PERSONNEL SHALL HAVE ANY LIABILITY TO YOU PURSUANT TO THIS AGREEMENT. Miscellaneous Entire Agreement. This Agreement, including all rules, policies and procedures incorporated herein by reference, constitutes the entire legal agreement between the Parties with respect to the Stuart Service. Drafting. No ambiguity will be construed against any Party based upon a claim that that Party drafted the ambiguous language. Severability. If any provision of this agreement is found by a court of competent jurisdiction to be invalid or unenforceable, then that provision will be removed from this agreement without affecting the rest of this agreement. The remaining provisions of this agreement will continue to be valid and enforceable. No Waiver. The waiver by either Party of any breach of this agreement does not waive any other breach. The failure of any Party to insist on strict performance of any covenant or obligation under this agreement will not be a waiver of such Party’s right to demand strict compliance in the future, nor will the same be construed as a novation of this agreement. Assignability. This agreement may not be delegated, assigned or transferred, in whole or in part, by you without prior written approval of Stuart. Stuart may assign or otherwise transfer this agreement in connection with a reorganization, consolidation, change of control, merger, acquisition or sale of substantially all of its assets that relate to this agreement. Any assignment in violation of the foregoing shall be null and void. Force Majeure. A Party shall not be liable for any failure of or delay in the performance of this agreement for the period that such failure or delay is due to causes beyond its reasonable control, including but not limited to acts of God, war, strikes or labor disputes, embargoes, government orders or any other force majeure event. Partner Policies and Rule of Conduct Attribution. You agree to display any attribution(s) required by Stuart as described in the documentation for the Stuart API. Stuart hereby grants you a non-transferable, non-sublicensable, non-exclusive license to display the Stuart trademarks that Stuart may, from time to time, provide and authorize you to use for the purpose of promoting or advertising that you use the Stuart APIs and/or the Stuart Service. Partner Operations. You will set-up and maintain operations (including any necessary employees or third-parties engaged by you for such operations) such that your items for each Confirmed Order are prepared and easily accessible for pick-up by a Stuart Messenger (the “Partner Operation”) during the period of time between the acceptance of such Confirmed Order and its respective Drop-Off Time Quote. API Limitations. Stuart may set limits on the number of API requests that you can make, at Stuart’s discretion. You agree to such limitations and will not attempt to circumvent such limitations. Monitoring. Stuart may monitor the use of the APIs to ensure quality, improve Stuart products and services, and verify your compliance with these terms. You will not interfere with such monitoring. Stuart may use any technical means to overcome such interference. Investigation. Stuart reserves the right to investigate any Application for compliance with these terms. Such investigation may include Stuart accessing and using the Application, for example to identify security issues that could affect Stuart or its customers or users. You consent to any such investigation. Stuart may suspend access to the Stuart APIs by you or the Application without notice if Stuart reasonably believes that you are in violation of these terms. Retrieval of User Content. When an end user’s non-public content is obtained through the Stuart APIs , you may not expose that content to other end users or to third parties without explicit opt-in consent from that user. Open Source. If any Application developed includes any open source software, (i) you have complied and will comply with all applicable open source software licensing terms and (ii) you have not and will not use any open source software in such a manner that would cause any software or Intellectual Property Rights of Stuart to be subject to any open source software licensing terms, restrictions or obligations. Use Restriction. You may not use the API or Stuart Data in any manner that is competitive to Stuart or the Stuart Service, including in connection with any application, website or other product or service that also includes, features, endorses, or otherwise supports in any way a third party that provides services competitive to Stuart’s products and services, in Stuart sole discretion. ©2015-2016 Stuart SAS Privacy Terms Contact us Logos & Resources EN