Get a Client
Gets one of the companies registered in your subscription (the one the token belongs to), found by its tax id and country. It returns the company's name, legal name, address, city, postal code, country, phone number, email and IBAN.
Endpoint
GET https://bo.magnifinance.com/api/v1.1/client?countryCode={CountryCode}&taxId={TaxId}
Request
Header
| Parameter | Required | Value |
|---|---|---|
| required | string(50) The email of an API user of your company. Example: api@yourcompany.pt | |
| Token | required | The token of the subscription whose companies you're looking up. |
note
*These parameters must be HTTP headers within the request.
Query
| Parameter | Required | Description |
|---|---|---|
| taxId | required | string(20) The tax id of the company you want to get. Example: ?taxId=599138645 |
| countryCode | required | string(2) The company's country, as an ISO 3166-1 alpha-2 code. Example: ?countryCode=PT |
Response
| Parameter | Description |
|---|---|
| RequestId | Unique Id for the request to have a way to identify the request |
| Object | |
| - NIF | string The company's tax id. Example: "166737755" |
| - Name | string The commercial name of the company. Example: "MagniFinance" |
| - Address | string The address of the company. Example: "Rua das Barreiras" |
| - City | string The city of the company. Example: "Lisboa" |
| - PostCode | string The postal code of the company. Example: "1000-000" |
| - CountryCode | string Company country code in ISO 3166-1 alpha-2. Example: "PT" |
| - PhoneNumber | string Company phone number. Example: "912345678" |
| - CountryName | string Name of the country. Example value: "Portugal" |
| - LegalName | string The company's legal name. Example value: "Empresa exemplar s.a" |
string The email of the company. Example value: "email@example.com" | |
| - IBAN | string Company international bank account number. Example value: "PT50002700000001234567833" |
| Type | int 0 = Success; 1 = Error; "Success" or "Error". Object will be returned on Success; ErrorValue, ErrorHumanReadable, ValidationErrors will be returned on Error. Example value: "0" |
| ErrorValue | MagniEnum |
| - Value | int Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "26" |
| - Name | string Identifies the error with a token. Example value: "NoClientFound" |
| ErrorHumanReadable | string Text that explains the error found. Example value: "ValidationError" |
| ValidationErrors | List of ValidationError |
| - Type | string Identifies the error with a token. Example value: "InvalidTaxId" |
| - Field | string Name of the field in which validation failed. Example value: "TaxId" |
| - ElementNumber | int Which element failed when the field repeats; 0 otherwise. Example value: 0 |
| - Detail | string Detailed error explanation. Example value: "Invalid Tax Id" |
| IsError | boolean Whether the request failed or not. Example value: "false" |
| IsSuccess | boolean Whether the request succeeded or not. Example value: "true" |
Errors
| ErrorValue | When |
|---|---|
NoClientFound (26) | There's no company with that tax id and country in your subscription. |
ValidationError (2) with InvalidTaxId | The tax id isn't valid for that country. |
AuthenticationError (1) | The email or token is wrong. |
Request Sample
Below you can check some examples of the REST request in some technologies.
cURL
curl --location --request GET 'https://bo.magnifinance.com/api/v1.1/client?countryCode=PT&taxId=599138645' \
--header 'email: api@yourcompany.pt' \
--header 'token: your-subscription-token'
Javascript (fetch)
var myHeaders = new Headers();
myHeaders.append("email", "api@yourcompany.pt");
myHeaders.append("token", "your-subscription-token");
var requestOptions = {
method: 'GET',
headers: myHeaders,
redirect: 'follow'
};
fetch("https://bo.magnifinance.com/api/v1.1/client?countryCode=PT&taxId=599138645", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
NodeJs (axios)
var axios = require('axios');
var config = {
method: 'get',
url: 'https://bo.magnifinance.com/api/v1.1/client?countryCode=PT&taxId=599138645',
headers: {
'email': 'api@yourcompany.pt',
'token': 'your-subscription-token'
}
};
axios(config)
.then(function (response) {
console.log(JSON.stringify(response.data));
})
.catch(function (error) {
console.log(error);
});
Python (requests)
import requests
url = "https://bo.magnifinance.com/api/v1.1/client"
headers = {
"email": "api@yourcompany.pt",
"token": "your-subscription-token"
}
params = {
"countryCode": "PT",
"taxId": "599138645"
}
response = requests.get(url, headers=headers, params=params)
print(response.json())
PHP (cURL)
<?php
$countryCode = "PT";
$taxId = "599138645";
$ch = curl_init("https://bo.magnifinance.com/api/v1.1/client?countryCode=" . $countryCode . "&taxId=" . $taxId);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"email: api@yourcompany.pt",
"token: your-subscription-token"
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
C# (HttpClient)
using System.Net.Http;
var client = new HttpClient();
client.DefaultRequestHeaders.Add("email", "api@yourcompany.pt");
client.DefaultRequestHeaders.Add("token", "your-subscription-token");
var response = await client.GetAsync("https://bo.magnifinance.com/api/v1.1/client?countryCode=PT&taxId=599138645");
Console.WriteLine(await response.Content.ReadAsStringAsync());
Java (HttpClient)
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://bo.magnifinance.com/api/v1.1/client?countryCode=PT&taxId=599138645"))
.header("email", "api@yourcompany.pt")
.header("token", "your-subscription-token")
.GET()
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Example Response
Success
{
"RequestId": "85f75487-4fc6-41a0-8e2e-3cef7e986560",
"Object": {
"NIF": "123456789",
"Name": "Empresa exemplar",
"Address": "Rua das Barreiras",
"City": "Lisboa",
"PostCode": "1234-567",
"CountryCode": "PT",
"PhoneNumber": "999999999",
"CountryName": "Portugal",
"LegalName": "Empresa exemplar s.a",
"Email": "email@exemplo.com",
"IBAN": "PT50002700000001234567833"
},
"Type": 0,
"ErrorValue": null,
"ErrorHumanReadable": null,
"ValidationErrors": null,
"IsSuccess": true,
"IsError": false
}
Error
{
"RequestId": "b4422f0e-0a98-489d-b058-f505a8666f2c",
"Object": null,
"Type": 1,
"ErrorValue": {
"Value": 2,
"Name": "ValidationError"
},
"ErrorHumanReadable": null,
"ValidationErrors": [
{
"Type": "InvalidTaxId",
"ElementNumber": 0,
"Field": "TaxId",
"Detail": "Invalid Tax Id"
}
],
"IsSuccess": false,
"IsError": true
}