Skip to main content

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​

ParameterRequiredValue
Emailrequiredstring(50) The email of an API user of your company. Example: api@yourcompany.pt
TokenrequiredThe token of the subscription whose companies you're looking up.
note

*These parameters must be HTTP headers within the request.

Query​

ParameterRequiredDescription
taxIdrequiredstring(20) The tax id of the company you want to get. Example: ?taxId=599138645
countryCoderequiredstring(2) The company's country, as an ISO 3166-1 alpha-2 code. Example: ?countryCode=PT

Response​

ParameterDescription
RequestIdUnique Id for the request to have a way to identify the request
Object
- NIFstring The company's tax id. Example: "166737755"
- Namestring The commercial name of the company. Example: "MagniFinance"
- Addressstring The address of the company. Example: "Rua das Barreiras"
- Citystring The city of the company. Example: "Lisboa"
- PostCodestring The postal code of the company. Example: "1000-000"
- CountryCodestring Company country code in ISO 3166-1 alpha-2. Example: "PT"
- PhoneNumberstring Company phone number. Example: "912345678"
- CountryNamestring Name of the country. Example value: "Portugal"
- LegalNamestring The company's legal name. Example value: "Empresa exemplar s.a"
- Emailstring The email of the company. Example value: "email@example.com"
- IBANstring Company international bank account number. Example value: "PT50002700000001234567833"
Typeint 0 = Success; 1 = Error; "Success" or "Error". Object will be returned on Success; ErrorValue, ErrorHumanReadable, ValidationErrors will be returned on Error. Example value: "0"
ErrorValueMagniEnum
- Valueint Identifies the error with a number. To identify the types of errors in more detail, click here. Example value: "26"
- Namestring Identifies the error with a token. Example value: "NoClientFound"
ErrorHumanReadablestring Text that explains the error found. Example value: "ValidationError"
ValidationErrorsList of ValidationError
- Typestring Identifies the error with a token. Example value: "InvalidTaxId"
- Fieldstring Name of the field in which validation failed. Example value: "TaxId"
- ElementNumberint Which element failed when the field repeats; 0 otherwise. Example value: 0
- Detailstring Detailed error explanation. Example value: "Invalid Tax Id"
IsErrorboolean Whether the request failed or not. Example value: "false"
IsSuccessboolean Whether the request succeeded or not. Example value: "true"

Errors​

ErrorValueWhen
NoClientFound (26)There's no company with that tax id and country in your subscription.
ValidationError (2) with InvalidTaxIdThe 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
}