Authentication and authorization

To access our API you need a valid API Key issued for target organization. This key will be used to authenticate the organization in which name you're doing requests.

---

Managing API Keys

You can manage API Keys for organization by using our API management tool. Each key can have optional limitations for IP addresses. If key has no IP addresses defined, then it can be used for doing requests from any place on the network. If there is at least one address asigned to the key, then only connection from IPs marked with Allow flag will be able to do requests with that key.

---

Using API Key

When sending a request to the API you need to put valid Key in the Authorization header of the HTTP request. Key value should be prefixed with scheme name Api-Key. Proper Authorization header value looks like this:

Returned values and codes

---

Returned values

Some methods of the API will return and object as a result of your request. Please check the documentation for detailed description of those objects.

---

Use of HTTP status codes

We're using standard HTTP status codes as a complementary information about state of processing. Anything in range 200-299 means that processing went properly, range 400-499 indicates an error most likely on your side, range 500-599 indicates problems on server's side. In case of problems, if possible, we'll return additional information as a body of response.

Typical codes returned from API are:

Code	Meaning
200	Everything is ok and some content was returned
204	Everything is ok but no content was returned (that's equvalent of void return type)
400	Most likely object(s) you've sent to the API didn't pass the validation
401	You're unauthorized to perform that request
403	You're unauthorized to perform that request as well
404	Wrong URL, please check with documentation
405	URL is fine, but you're using wrong HTTP method (eg. GET instead of POST etc.)
408	Our servers are busy, please try again later
409	Request operation can't be executed as it would lead to invalid data state
415	You've posted or requested data in format that isn't handled by our API. Check the documentation - each method has list of data formats it accepts and can return
500	We have some bug in our code, let us know and we'll fix it
503	Something went really wrong, please try again later

How to read endpoints documentation

Key elements

Each endpoint has multiple methods, that you send requests to. In the documentation of the method you'll find key elements:

Name	Purpose
Path	Relative path to the method, combine it with one of the servers listed in Servers section to form target URL of your request. If method requires some values to be passed in path or query string of the URI, then you'll find their names placed in curly brackets (eg. clientId={clientId})
HTTP method	The HTTP method you need to use when sending a request. That can be one of: GET, POST, PATCH, PUT, DELETE.
Accepts	If method accepts input data in form of request body, then here you'll see listed possible data formats that you can send data in. Note that you must indicate which format you're using by sending Content-Type header with one of those values.
Returns	If method returns output data in form of response body, then here you'll see listed possible data formats in which we can send that data back to you. Note that you must indicate which format you want by sending Accepts header with one of those values. If you'll not send such header, then we'll send back data in JSON format.
Authorization	List of possible authorization methods, that you can use for the request. If none listed, then method doesn't need authorization at all.
Inputs	This list will display detailed informations about all parameters that method can or needs to take as an input.
Output	If method returns something, then here you'll see details about object it returns.
Type (of Input parameter or Output value)	Name of the type of the parameter. If you see an icon beside it, you can click it to display modal with nested list of properties, that this type consists of. You'll also see description of the property, possible values (Presented this way), type of the property (Presented this way) and constrains (Presented this way).
Source (of Input parameter)	Can be one of: Uri, Body, Header. Indicates where you should put value of that parameter.
Examples	Here you can click on the icons, to display printout of some randomly generated object of given type, encoded in each of the possible input/output data types. Just so you can take a feel of how it will/should look like.

Servers

You can access our API with different servers, each setup for different usage scenarios. Here's the list of them:

Name	Base URL	Description
Test	http://api.kidnet.qa.makingdatahuman.com	Test server to which you can freely post test data.
Production	https://api.comc.ametrics.org	Production server which you should use only after you're sure that your API implementation is working

Batch processing

You can use /BatchInput endpoint to send us aggregated list of commands that you want to execute in our API one-by-one. After processing your batch input request we can callback URL provided to let you know that batch processing has finished. This way of interacting with KIDNet is meant for very large portions of data, that you want to send to us. In standard situations please use other provided endpoints as those give you better control over the API.

Keep in mind that batch input has following constrains:

• Not all commands are available (we've marked batchable commands with Callable in batch mode bagde beside command's name).
• It's all-or-nothing method. We're executing your batch in transaction so if anything fails in the middle of the batch, all previous data changes will be rolledback.
• We don't guarantee when import will actually happen. Our servers will make their best to process your batch as soon as possible but it also can be queued after other requests.

Capturing and using variables

Sometimes you would need to use in one command some value returned from other command of our API. Let's say you're creating new Client with /Clients/AddClient method and then you want to admit that client with /Clients/AdmitClient method. AdmitClient requires you to provide identificators of Clinician, Program and just created Client. To cover such scenarios we've introduced variables. You can use ResultVariable field to provide us name under which we'll capture output of the command. Then you can use that same name in next commands in the batch to insert value from the previous command.

Example

{ "Commands": [ { "Endpoint": "Clients", "Action": "AddClient", "Data": { "FirstName": "Test 1", "MiddleName": null, "LastName": "Batch", "Ssn": "123-22-1233", "BirthDate": "1991-10-28", "Gender": "Female", "Address": "Addr 1", "Address2": "Addr 2", "Address3": "Addr 3", "City": "Bydgoszcz", "State": "VT", "ZipCode": "12300", "Telephone": "+48123123123", "English": true, "Language": "Polish", "Race": "WhiteOrEuroAmerican", "RaceOther": null }, "ResultVariable": "CLIENT_1_RESULT" }, { "Endpoint": "Clients", "Action": "AdmitClient", "Data": { "ClientId": "%CLIENT_1_RESULT.ClientId%", "ProgramId": 461, "ClinicianId": 5724 } } ] }

As you can see above first command to be executed is /Clients/AddClient, result of that command will be stored in CLIENT_1_RESULT variable. Then next command is picked up, that is /Clients/AdmitClient. In the there we use %CLIENT_1_RESULT.ClientId% placeholder to tell batch processor that it should put value of the property ClientId found on CLIENT_1_RESULT captured variable.

Notation

To indicate that you want to use captured variable put it's name between percent signs (%). Use dots to create a path to the property which value you want to be used. In example above we've captured AddClient's output to CLIENT_1_RESULT variable. That output is of type AddClientResponse. That's a complex type and it has property called ClientId in which you'll find identificator of just created Client. So to put that identificator's value in next command you need to use %CLIENT_1_RESULT.ClientId% path.

Lists

If your variable is a list (like output of /Clients/GetClients command) then you can access one of the items of that list by it's index. Just put the index number as you would normal property. For example: %LIST_RESULT.0.Id% will return value of Id of the object that's under index 0 on the LIST_RESULT list variable.

Another example

{ "Commands": [ { "Endpoint": "Clients", "Action": "GetClients", "Data": { "ExternalId": "EX1234" }, "ResultVariable": "FoundClients" }, { "Endpoint": "Clients", "Action": "AdmitClient", "Data": { "ClientId": "%FoundClients.Clients.0.Id%", "ProgramId": 123, "ClinicianId": 1234 } } ] }

In this example we're searching for the client with ExternalId equal to EX1234. /Clients/GetClients endpoint returns a list of found clients (note: ExternalId is managed by you, so there can be multiple clients in your organization with same ExternalId if you set them so). Next we want to admit such client to the program, we can use %FoundClients.Clients.0.Id% path to obtain first client's Id (lists have zero-based indexes).

Scope and overwriting

Your batch input is processed one-by-one from top to bottom of the list of commands. Any variables captured are effective from next command after one where you've captured the output to the very end of the batch.

If you'll use same variable name twice then previous value of that variable will be overwritten by new value. One variable name can store only one value.

Callback

You can provide a callback URL address (use BatchInputRequest.Metadata.CallbackAddress property), to which we'll send a HTTP POST request once we finish processing of your batch. Data posted to the callback endpoint will have detailed report about how the processing went, if there were any errors and if then at what location of your input problems occured.

We can even send you back captured variables - just use BatchInputRequest.Metadata.ReturnVariables property to list variables or paths that you're interested in and we'll send them back to your callback URL if processing will succeed.

Please note that:

• Callback must be an HTTP accessible address on the internet.
• We'll send our report in application/json format.
• What's also important is that we'll timeout the HTTP request after just 5 seconds, so be sure to NOT do any time intensive tasks within your callback endpoint routine. Just get the data, store it somewhere and trigger further processing on the different thread.
• We'll try to send the report only once. If by any reason we would not be able to communicate with your endpoint no further retry attempts will be made.

Client libraries

Language	Download link
.NET >= 4.5	dotNet45.zip

What's inside the library

KIDNet API's library provides:

• Interfaces for each endpoint we expose in our API, you can use these definitions to create classes implementing client functionality
• Data Transfer Objects that are used in communication with our API, you can use them directly in your code to build the requests and as deserialization target for the output from API
• Enums just like DTOs these are the ones you can use directly in your code when communicating with the API
• Validation annotations and other markers on endpoints and DTOs that can help you validate interchanged data before it leaves your system and when it cames back

Library does not provide ready-to-go client that you can use to connect with the API - that last part is up to you to create with the approach and technology you want.