Quick-start guide


ABOUT OUR APIs

The NaviPlan® APIs from Advicent provide the necessary toolkit for integrating our suite of financial planning engines and retrieving data from financial plans to build a range of new user experiences for both clients and advisors. This development portal provides detailed information about our API services as well as data definitions and common examples to get your development team building new functionalities quickly.

If you require any additional assistance while exploring our APIs, please contact Tier2Support@advicent.com. You can also review our Terms of Use for specific conditions regarding any usage of the NaviPlan APIs.

MAKING A CALL

The base URL for the development instance of your system is dependent on your contract agreement. Please contact Tier2Support@advicent.com for questions or issues about connectivity and your base URL.

All communications with our APIs should be done using HTTPS to ensure secure communication of data. Pre-production development may be done at a lower security posture as your security department or secure software development lifecycle dictates.

The APIs are based on RESTful principles with resource-oriented URL service contracts. All requests and responses are communicated in the JSON format. The HTTP status codes are used to indicate success or failure of the request. Following the RESTful design, all requests should be made to the API services using the appropriate HTTP verb which defines the desired action:

Verb Description
GET Use the GET verb to retrieve information. This will always be a read-only request, so queried objects shall never be modified by a GET request
POST Use the POST verb to create a new object in the system. Request parameters can be given as a JSON message. The response body will generally return a newly created resource.
PUT Use the PUT verb to update a resource in the system. As with a POST request, the parameters are sent as a JSON formatted message. If successful, the response body generally returns the updated resource
DELETE       Use the DELETE verb to delete a resource. Successful DELETE requests return an empty response body.

RESPONSES

All non-empty response bodies, including errors, will be formatted as a JSON message. A valid GET request will return an object with the data contained within a single key-value pair. The key is always associated with the appropriate API service.

If you are requesting multiple entries, such as a collection of resources, the data will be returned as an array. If you are requesting a single entity, the resource data will be returned as an object. The APIs use standard HTTP status codes to communicate the status of a request.

Code Meaning Definition
200 OK The request was successful and the expected data is in the response body where applicable.
201 CREATED The creation of the new resource was successful. Typically the newly created resource will be found in the response body.
204 NO CONTENT The deletion of a resource was successful however there is no information to return in the response body.
400 BAD REQUEST There was an error parsing the request parameters.
401 UNAUTHORIZED The credentials or API application key / tokey are incorrect.
403 FORBIDDEN You do not have access to the requested service or action.
404 NOT FOUND The resource requested does not exist.
409 CONFLICT This indicates that you are trying to perform an action that will cause a conflict with either the data or a process running within the system.
500 INTERNAL SERVER ERROR An internal server error has occurred that could be data, process, or API related.

ERRORS

Example

Error Response Body

{
  "message": "..."
}

Error Response Code

401

AUTHENTICATION

Most endpoints in the APIs require an authenticated user session to succeed. If no user session is found, you will receive a 401 Unauthorized response. The API uses cookies and session managment to maintain a user's session once authenticated. To begin an authenticated session, use the auth\Login endpoint as shown below:

Request URL

https://us-naviplan.uat.narratorsolutions.com/api/auth/Login

Parameter: model

{
  "username": "testUser",
  "password": "Adv!c3ntR0cks!",
  "npoIdentifiers": [
    "optional"
  ]
}

Curl

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"username\": \"testUser\",
  \"password\": \"Adv!c3ntR0cks!\",
  \"npoIdentifiers\": [
    \"optional\"
  ]
}" "https://us-naviplan.uat.narratorsolutions.com/api/auth/Login"

The value for the npoIdentifier parameter will be dependent on your contract agreement. Please contact Tier2Support@advicent.com for questions or issues regarding authentication.