GoCardlessDeveloper Docs
Create a sandbox account

Verification Detail

View as Markdown

Verification details represent any information needed by GoCardless to verify a creditor.

Restricted: These endpoints are restricted to customers who want to collect their merchant's verification details and pass them to GoCardless via our API. Please get in touch if you wish to enable this feature on your account.

Create a verification detail#

POST/verification_details

Creates a new verification detail

POST https://api.gocardless.com/verification_details/ HTTP/1.1
Content-Type: application/json
{
  "verification_details": {
    "name": "Acme Limited",
    "company_number": "03768189",
    "description": "wine and cheese seller",
    "address_line1": "12 Drury lane",
    "city": "London",
    "postal_code": "B4 7NJ",
    "directors": [{
      "date_of_birth": "1986-02-19",
      "given_name": "Gandalf",
      "family_name": "Grey",
      "city": "London",
      "street": "Drury Lane",
      "postal_code": "B4 7NJ",
      "country_code": "GB"
    }],
    "links": {
      "creditor": "CR123"
    }
  }
}
@client.verification_details.create(params: {
  name: "Acme",
  company_number: "03768189",
  address_line1: "12 Drury lane",
  city: "London",
  description: "wine and cheese seller",
  postal_code: "B4 7NJ",
  directors: [{
    given_name: "Gandalf",
    family_name: "Grey",
    city:  "London",
    date_of_birth: "1986-02-19",
    street: "Drury lane",
    postal_code: "B4 7NJ",
    country_code: "GB",
  }],
  links: {
    creditor: "CR123",
  },
})
client.verification_details.create(params={
  "name": "Acme",
  "company_number": "03768189",
  "address_line1": "12 Drury lane",
  "city": "London",
  "description": "wine and cheese seller",
  "postal_code": "B4 7NJ",
  "directors": [{
    "given_name": "Gandalf",
    "family_name": "Grey",
    "city":  "London",
    "date_of_birth": "1986-02-19",
    "street": "Drury lane",
    "postal_code": "B4 7NJ",
    "country_code": "GB"
  }],
  "links": {
    "creditor": "CR123"
  }
})
const verificationDetail = await client.verificationDetails.create({
  name: "Acme",
  company_number: "03768189",
  address_line1: "12 Drury lane",
  city: "London",
  description: "wine and cheese seller",
  postal_code: "B4 7NJ",
  directors: [{
    given_name: "Gandalf",
    family_name: "Grey",
    city: "London",
    date_of_birth: "1986-02-19",
    street: "Drury lane",
    postal_code: "B4 7NJ",
    country_code: "GB"
  }],
  links: {
    creditor: "CR123"
  }
});
$verification_details = $client->verificationDetails()->create([
  'params' => [
    'name' => 'Acme',
    'company_number' => '03768189',
    'address_line1' => '12 Drury lane',
    'city' => 'London',
    'description' => 'wine and cheese seller',
    'postal_code' => 'B4 7NJ',
    'directors' => [[
      'given_name' => 'Gandalf',
      'family_name' => 'Grey',
      'city' =>  'London',
      'date_of_birth' => '1986-02-19',
      'street' => 'Drury lane',
      'postal_code' => 'B4 7NJ',
      'country_code' => 'GB'
    ]],
    'links' => [
      'creditor' => 'CR123'
    ]
  ]
]);
import com.gocardless.services.VerificationDetailService.VerificationDetailCreateRequest.Directors;

Directors director = new Directors();

director.withCity("London");
director.withCountryCode("GB");
director.withDateOfBirth("1986-02-19");
director.withGivenName("Gandalf");
director.withFamilyName("Grey");
director.withPostalCode("B4 7NJ");
director.withStreet("Drury Lane");

VerificationDetail verificationDetail = client.verificationDetails().create()
  .withName("Acme")
  .withDescription("wine and cheese seller")
  .withCompanyNumber("03768189")
  .withAddressLine1("12 Drury Lane")
  .withCity("London")
  .withPostalCode("B4 7NJ")
  .withDirectors(director)
  .withLinksCreditor("CR123")
  .execute();
verificationDetailCreateParams := gocardless.VerificationDetailCreateParams{
  Name:          "Acme",
  CompanyNumber: "03768189",
  AddressLine1:  "12 Drury lane",
  City:          "London",
  Description:   "wine and cheese seller",
  PostalCode:    "B4 7NJ",
  Directors: []gocardless.VerificationDetailCreateParamsDirectors{
    {
      GivenName:   "Gandalf",
      FamilyName:  "Grey",
      City:        "London",
      DateOfBirth: "1986-02-19",
      Street:      "Drury Lane",
      PostalCode:  "B4 7NJ",
      CountryCode: "GB",
    },
  },
  Links: gocardless.VerificationDetailCreateParamsLinks{
    Creditor: "CR123",
  },
}

verificationDetail, err := client.VerificationDetails.Create(ctx, verificationDetailCreateParams)
if err != nil {
  fmt.Printf("error creating verification detail: %s", err.Error())
  return
}
var verificationDetailCreateRequest = new GoCardless.Services.VerificationDetailCreateRequest()
{
  Name = "Acme",
  CompanyNumber = "03768189",
  AddressLine1 = "12 Drury lane",
  City = "London",
  Description = "wine and cheese seller",
  PostalCode = "B4 7NJ",
  Directors = new GoCardless.Services.VerificationDetailCreateRequest.VerificationDetailDirectors[]
  {
    new GoCardless.Services.VerificationDetailCreateRequest.VerificationDetailDirectors
    {
      GivenName = "Gandalf",
      FamilyName = "Grey",
      City =  "London",
      DateOfBirth = "1986-02-19",
      Street = "Drury lane",
      PostalCode = "B4 7NJ",
      CountryCode = "GB"
    }
  },
  Links = new GoCardless.Services.VerificationDetailCreateRequest.VerificationDetailLinks()
  {
    Creditor = "CR123"
  }
};

var verificationDetailResponse = await client.VerificationDetails.CreateAsync(verificationDetailCreateRequest);

var verificationDetail = verificationDetailResponse.VerificationDetail;
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "verification_details": {
    "name": "Acme Limited",
    "company_number": "03768189",
    "description": "wine and cheese seller",
    "address_line1": "12 Drury lane",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "B4 7NJ",
    "country_code": "GB",
    "directors": [{
      "given_name": "Gandalf",
      "family_name": "Grey",
      "date_of_birth": "1986-02-19",
      "street": "Drury lane",
      "city": "London",
      "postal_code": "B4 7NJ",
      "country_code": "GB"
    }],
    "links": {
      "creditor": "CR123"
    }
  }
}
Request Body
verification_detailsobject
10 properties
namestring

The company's legal name.

company_numberstring

The company's registration number.

descriptionstring

A summary describing what the company does.

address_line1string

The first line of the company's address.

address_line2string

The second line of the company's address.

address_line3string

The third line of the company's address.

citystring

The city of the company's address.

postal_codestring

The company's postal code.

directorsarray

The company's directors.

7 properties
given_namestring

The person's given name.

family_namestring

The person's family name.

date_of_birthstring

The person's date of birth.

streetstring

The street of the person's address.

citystring

The city of the person's address.

postal_codestring

The person's postal code.

country_codestring
linksobject
1 properties
creditorstring

ID of the associated creditor.

Response 201

Resource created successfully

verification_detailsobject
12 properties
namestring

The company's legal name.

company_numberstring

The company's registration number.

descriptionstring

A summary describing what the company does.

address_line1string

The first line of the company's address.

address_line2string

The second line of the company's address.

address_line3string

The third line of the company's address.

citystring

The city of the company's address.

postal_codestring

The company's postal code.

regionstring

The region of the company's address.

country_codestring

The country code of the company's address.

directorsarray

The company's directors.

7 properties
given_namestring

The person's given name.

family_namestring

The person's family name.

date_of_birthstring

The person's date of birth.

streetstring

The street of the person's address.

citystring

The city of the person's address.

postal_codestring

The person's postal code.

country_codestring
linksobject
1 properties
creditorstring

ID of the creditor

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject

List verification details#

GET/verification_details

Returns a list of verification details belonging to a creditor.

GET https://api.gocardless.com/verification_details?creditor=CR123 HTTP/1.1
@client.verification_details.list(params: {
  creditor: "CR123",
}).records
client.verification_details.list(params={
  "creditor": "CR123"
}).records
const verificationDetailList = await client.verificationDetails.list({ creditor: "CR123" });
$response = $client->verificationDetails()->list([
  'params' => [
    'creditor' => 'CR123'
  ]
])->records;
for (VerificationDetail verificationDetail: client.verificationDetails().all().withCreditor("CR123").execute()){
  System.out.println(verificationDetail.getDescription());
}
verificationDetailListParams := gocardless.VerificationDetailListParams{
  Creditor: "CR123",
}
verificationDetailList, err := client.VerificationDetails.List(ctx, verificationDetailListParams)
if err != nil {
  fmt.Printf("error listing verification details: %+v", err)
  return
}

for _, verificationDetail := range verificationDetailList.VerificationDetails {
  fmt.Println(verificationDetail.Name)
  fmt.Println(verificationDetail.Description)
}
var verificationDetailListRequest = new GoCardless.Services.VerificationDetailListRequest()
{
  Creditor = "CR123"
};

var verificationDetailListResponse = client.VerificationDetails.All(verificationDetailListRequest);
foreach (var verificationDetail in verificationDetailListResponse)
{
  Console.WriteLine(verificationDetail.Description);
}
Responsehttp
HTTP/1.1 200 OK
Content-Type: application/json
{
  "verification_details": [{
    "name": "Acme Limited",
    "company_number": "03768189",
    "description": "wine and cheese seller",
    "address_line1": "12 Drury lane",
    "address_line2": null,
    "address_line3": null,
    "city": "London",
    "region": null,
    "postal_code": "B4 7NJ",
    "country_code": "GB",
    "directors": [{
      "given_name": "Gandalf",
      "family_name": "Grey",
      "date_of_birth": "1986-02-19",
      "street": "Drury lane",
      "city": "London",
      "postal_code": "B4 7NJ",
      "country_code": "GB"
    }],
    "links": {
      "creditor": "CR123"
    }
  }]
}
Response 200

Successful response

verification_detailsarray
12 properties
namestring

The company's legal name.

company_numberstring

The company's registration number.

descriptionstring

A summary describing what the company does.

address_line1string

The first line of the company's address.

address_line2string

The second line of the company's address.

address_line3string

The third line of the company's address.

citystring

The city of the company's address.

postal_codestring

The company's postal code.

regionstring

The region of the company's address.

country_codestring

The country code of the company's address.

directorsarray

The company's directors.

7 properties
given_namestring

The person's given name.

family_namestring

The person's family name.

date_of_birthstring

The person's date of birth.

streetstring

The street of the person's address.

citystring

The city of the person's address.

postal_codestring

The person's postal code.

country_codestring
linksobject
1 properties
creditorstring

ID of the creditor

metaobject
2 properties
limitinteger
cursorsobject
2 properties
beforestring

Cursor pointing to the end of the desired set.

afterstring

Cursor pointing to the start of the desired set.

Errors 400401404422500
400

Bad Request

401

Unauthorised

404

Not found

422

Validation Error

500

Internal Error

Error Body
codeinteger
documentation_urlstring
errorsarray
2 properties
reasonstring
messagestring
messagestring
request_idstring
typestring
metadataobject
linksobject