Welcome to the Moovago API Getting Started Guide!
The Moovago API allows you to create/read/modify/delete your various data stored in Moovago, in a programmatic way (= data exchange with your ERP, your servers…).
This guide shows you how to configure and use our API.
The elements currently offered by the API are those requested by our customers. If you have any other requirements or questions/comments, please let us know at support@moovago.com.
It’s useful to understand the names of a few elements of the Moovago application.
Our API endpoints require API key authentication.
If you do not yet have a Moovago API key, please contact us at support@moovago.com.
To authenticate yourself, simply add your API key to your request header.
(Refer to the instructions provided in the e-mail you received with your API key)
The Moovago API works with GraphQL.
Here’s what a GraphQL QUERY might look like:
{ "query": "{ team { id name members { id alias } } }" }
or (you can also specify a custom query name if you prefer):
{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }
Sometimes you can provide input parameters (= variables) to filter the results (here, a teamId for example):
Be careful, you must escape the quotation marks from the variable values!
{ "query": "{ companyList(filter: { teamId: \"XYZ\" }) { id name ownerIds } }" }
or (you can also use the variables field in a named query if you prefer):
This does not require escaping quotes => “must be written “
{ "query": "query MyCompanyListQuery($filter: FilterManyCompanyInput!) { companyList(filter: $filter) { id name ownerIds } }", "variables": { "filter": { "teamId": "XYZ" } } }
This is what a GraphQL MUTATION query might look like :
{ "query": "mutation { company { create( input: { ownerIds: [\"XYZ\"], name: \"Moovago\", city: \"Niort\", address: \"46 Rue du 14 Juillet\", postalCode: \"79000\", phone: \"07 68 45 46 74\", email: \"support@moovago.com\", note: \"L application du commercial\" } ) { recordId } } }" }
or (you can also use the variables field in a named query if you prefer):
{ "query": "mutation MyCompanyCreate($input: CompanyCreateInput!) { company { create(input: $input) { recordId } } }", "variables": { "input": { "ownerIds": ["XYZ"], "name": "Moovago", "city": "Niort", "address": "46 Rue du 14 Juillet", "postalCode": "79000", "phone": "07 68 45 46 74", "email": "support@moovago.com", "note": "L application du commercial" } } }
Before continuing, you may wish to consult the graphql.org documentation to learn more.
We recommend you use a GraphQL client to help you write, send and test your GraphQL queries, such as: Altair GraphQL Client
Introspection is disabled on our server. So you can’t retrieve the GraphQL schema directly from our server.
However, you can download the Moovago API GraphQL schema file here: moovago_api_graphql_schema.gql
and import it into the Altair client (In Altair’s top-right window, click on: Docs ->… -> Load Schema…)
Below are some examples of QUERY and MUTATION queries using the curl command line tool (replace <your-api-key> with the value of your API key).
You must also add the following header to your requests:
Content-Type: application/json
QUERY :
Retrieve your team and team members:
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "query MyTeamQuery { team { id name members { id alias } } }" }'
Retrieve the list of your principals (replace ‘<your-teamId>’):
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "query MyMandatorList($filter: FilterManyMandatorInput!) { mandatorList(filter: $filter) { id name } }", "variables": { "filter": { "teamId": "<your-teamId>" } } }'
MUTATION :
Create a new company (replace ‘<ownerId-value>’):
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "mutation MyCompanyCreate($input: CompanyCreateInput!) { company { create(input: $input) { recordId } } }", "variables": { "input": { "ownerIds": ["<ownerId-value>"], "name": "Moovago", "city": "Niort", "address": "46 Rue du 14 Juillet", "postalCode": "79000", "phone": "07 68 45 46 74", "email": "support@moovago.com", "note": "L application du commercial" } } }'
Modify an existing company (replace ‘<companyId-value>’):
curl https://<api-backend>/graphql \
-X POST \
-H '<your-api-key>' \
-H 'Content-Type: application/json' \
-d '{ "query": "mutation MyCompanyUpdate($input: CompanyUpdateInput!) { company { update(input: $input) { recordId } } }", "variables": { "input": { "id": "<companyId-value>", "input": { "note": "Here is my new note"} } } }'
See our GraphQL API reference documentation for a list of all possible queries, as well as all the details of our API.
GraphQL APIs can return both correct data and errors in parallel. This is why the Moovago API will return HTTP 200 codes even if there are errors.
By default, errors are contained in an errors table. You’ll find a description of each error in the “message” field.
It’s up to you to detect and manage these errors. For example, by intercepting all our API responses and checking the errors array .
Here’s what a GraphQL response containing an error might look like:
{
"data": null,
"errors": [
{
"message": "You are not authorized to access this data",
"locations": [],
"errorType": "DataFetchingException",
"path": [
"companyList"
],
"extensions": null
}
]
}
Errors returned by mutations
By default, errors returned by mutations are as described in the previous section.
But mutations can also return user and business logic errors, directly in the “data” sub-data. This allows you to separate these mutation-specific errors from the global-level errors seen earlier (used then only for analysis errors and other more general server-side errors).
All these mutation-specific errors are named with the suffix “Problem” (equivalent to an error code). Each mutation can return one or more errors. And each mutation describes the types of error it can return. You can then use it on the client side to easily identify errors. Some error types can also be accompanied by additional error metadata.
Example
To retrieve errors specific to mutations, use the “message” field to retrieve textual error messages and the “__typename” field containing the error code ( Problem type).
We will therefore add the following code to the queries to retrieve the values of these 2 fields (for each of the errors returned):
errors {
__typename
... on Problem {
message
}
}
For example, for the mutation company create :
{ "query": "mutation { company { create( input: { ownerIds: [\"Space caracter is not allow here\"], name: \"Moovago\", city: \"Niort\", address: \"46 Rue du 14 Juillet\", postalCode: \"79000\", phone: \"07 68 45 46 74\", email: \"support@moovago.com\", note: \"L application du commercial\" } ) { recordId errors { __typename ... on Problem { message } } } } }" }
and the response containing a MalformedParameterProblem error with a text message describing the error in more detail:
{
"data": {
"company": {
"create": {
"recordId": null,
"errors": [
{
"__typename": "MalformedParameterProblem",
"message": "An input parameter is empty, or contains an illegal character."
}
]
}
}
},
"errors": null
}
HTTP response codes
It is also possible for the Moovago server to return conventional
HTTP codes to indicate the success or failure of a request.
In general, codes 2xx indicate success (unless the errors table is not empty).
Codes 4xx indicate that an error has occurred in the data supplied.
Codes 5xx indicate an error originating from the Moovago servers.
200
Ok
Everything went according to plan.
429
Too Many Requests
Too many requests reached the API too quickly. ( 5 requests max / second).
5xx
Server Errors
Something has gone wrong on the Moovago server.
For your first tests, we suggest you import some of your data one by one, to test and make sure each time that the data has been imported with the right values, and in the right fields. And only then import all your data en masse, at a reasonable rate (ideally 1 query max / second).
Server limits for the API are currently set at :
If this limit is exceeded, the server will respond with a status code 429 Too Many Requests
On the Production server, please program your mass processing to take place outside the following times:
Monday to Friday, 8am to 6.30pm
The Moovago API regularly evolves to offer new functionalities, most of the time without affecting your connector. Occasionally, however, we may have to deprecate certain elements of the API. These elements are then indicated in our reference documentation as deprecated for a few months, so that you have time to update your connector. Deprecated elements are then removed completely.
It is your responsibility to keep your connector up to date. You must not use any more deprecated elements before they are removed, otherwise your connector will no longer work.