IDS Developer Resources

API
Your Data. Real Time.


  • Is there documentation for the Api?

    Yes, you can find documentation here.

    In addition, there is a sample postman collection you can Download with instructions that can be used for development and testing in the IDS Api test environment.


  • Is there a developer test environment?

    Yes, you will need to request a clientid for the test environment. You can request a test clientid by contacting api@ids-astra.com. The clientid should be treated like a password, so keep it safe and hidden.


  • How do I get an access token to consume the api?

    Initiate a call to the token endpoint. Use your issued clientid for the test environment (this is required in the request payload when you call the Token endpoint). The token endpoint will respond with an access token.

                                    Sample Request
                                    {
                                        "ClientId":"y37Q5JdKt9ucLaPH94broLZvTErTmrZY"
                                    }
                                    Sample Response
                                    {
                                        "ClientId": "y37Q5JdKt9ucLaPH94broLZvTErTmrZY",
                                        "AccessToken": "access_token",
                                        "ExpiryTime": "2018-06-06T18:22:20.2572726-04:00",
                                        "ExpiresInSeconds": 86364
                                    }
                                    


  • How to use an access token to consume an api resource?

    Using the AccessToken, add an Authorization request header to every API request:

    Authorization Bearer {AccessToken}

    Refer to the sample postman collection to demonstrate several examples of how to consume the various api resources.


  • Does the access token expire?

    Yes, access tokens will expire. The default expiry time is 24 hours, however this may change at anytime. When an access token expires, you will receive an http status code of 401. For this reason, you should ensure that every http response is checked for this status code. When this happens, call the token endpoint again to refresh your access token.


  • Are there any api rate limits?

    Yes, there is a limit to the number of requests per second per dealer. There are many factors that contribute to rate limitting but the default is 10 requests/second, however this may change at any time. When rate limitting is enforced, you will receive a http status code of 429. When this happens, you should attempt to retry using an exponential backoff pattern.


  • What are the minimum dealership requirements?

    Minimum 12.1.3 Astra/G2 Release. Astra server will require a static IP Address.


  • What is a subscription?

    A subscription is when you subscribe to a resource. You would subscribe to a resource if for example you want to be notified that a resource has been added, updated or deleted.


  • Which resources can I subscribe to?

    The customers and units resources can be subscribed to.


  • How do I subscribe to customer notifications?

    You can subscribe by calling the /Customers/Subscribe/{Location} endpoint. Part of the request payload is a callback url or webhook which you must provide. The callback url must be active when you subscribe, otherwise the subscribe endpoint will return with a failure code.

    The location parameter must be a valid dealer location code.


  • Can I have multiple subscriptions for the same resource?

    For most use cases, we allow for one subscription per resource.

    However, there are some edge cases where you can subscribe to the same resource for more than one location. In this case be sure to have a separate callback url for each resource location.


  • When do subscriptions expire?

    Yes, subscriptions will automatically expire after 30 days. For this reason, you must renew your subscription before the 30 day period. You can simply renew your subscription by calling the same subscription endpoint.

    Another reason that a subscription can expire is if the callback url continuously fails for 7 days. If this happens, simply renew your subscription with a valid callback url.


  • How can I check the status of my subscriptions?

    The simplest way to check your subscriptions is by calling the /Subscribe/ALL endpoint. This will give you information on all of your subscriptions and you can use the CreatedDateTimeUtc property to determine when you should renew your subscription.


  • How can I retrieve all customer data?

    You can retrieve all customer data by enumerating through the alphabet and performing a wildcard search in the last name field like so:

                                
                                    {
                                        "Location": "{{TestingLocation}}",
                                        "Filters": {
                                        "LastName": "A]"
                                        }
                                    }
                                    


  • How can I know which customers purchased a unit?

    The PurchCustNo field in the Units resource will contain the customer number who purchased the stock unit.