How to integrate with the API

Covve Scan API

Request

The client should make an HTTP POST request to a specific endpoint with the provided API key in the Authorization header and the image of the scanned card

Endpoint URL

HTTP POST https://app.covve.com/api/businesscards/scan

Input Parameters

Include Authorization Header with value your API Key. For example in Postman you should do the below:
Include Content-Type Header with value multipart/form-data
Include the cropped image of a business card (resolution approximately 900x500, maximum size 4MB), with key file.
[optional] Include the parseAddress parameter in the form. Its type is boolean. If this is set to true and the option is enabled for the API Key, then the parsedAddress field of each address will be populated. Otherwise this field will be left to null.
[optional] Include the fixNameCapitalization parameter in the form. Its type is boolean. If this is set to true then if the name on the card is written in capital letters it will be returned in title case. E.g. JOHN DOE -> John Doe

Response

The response with all the data on the card will be in JSON format

Possible Response Codes:

400 Bad Request in case of malformed request
400 Bad Request in case of an error in scanning
200 OK in case of successful scanning with the below payload in JSON format

Response Payload upon successful scan:

{
    "language": "en",
    "id": "eb8c5067-c2bf-446b-a25f-90201c703514",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "M.",
    "emails": [
        {
            "address": "john.doe@mail.com"
        }
    ],
    "phones": [
        {
            "number": "123 123 1234",
            "type": "Work"
        }

    ],
    "jobs": [
        {
            "company": "ACME",
            "title": "CEO"
        }
    ],
    "websites": [
        {
            "url": "www.acme.com"
        }
    ],
    "notes": "some notes",
    "addresses": [
        {
            "fullAddress": "22 Park Ln, London W1K 1BE, United Kingdom",
            "parsedAddress": {
                "street": "22 Park Ln",
                "postalCode": "W1K 1BE",
                "city": "London",
                "state": null,
                "country": "United Kingdom",
                "latitude": "51.509646654",
                "longitude": "0.150322466"
            }
        }
    ]
}

Response Payload Fields

language: string - the identified language of the card - always exists
id: string - a UUID describing this scan uniquely - always exists
firstName: string - the first name identified on the card - exists if identified or an empty string
lastName: string - the last name identified on the card - exists if identified or an empty string
middleName: string - the middle name identified on the card - exists if identified or empty string
emails: array - of the identified emails on the card. If no emails are identified then the array is empty. Each object in the array has the below fields:
- address: string - the email address identified
phones: array - of the identified phones on the card. If no phones are identified then the array is empty. Each object in the array has the below fields:
- number: string - the phone number identified. No formatting is applied here. It's served as presented on the card. E.g if there are parenthesis, country codes, and dashes, we keep everything in the result.
- type: string - the phone type identified. Possible values are Work, Home, Mobile, FaxWork or an empty string if no type is identified.
jobs: array - of the identified jobs on the card. If no jobs are identified then the array is empty. Each object in the array has the below fields:
- company: string - the company name identified on the card
- title: string - the job title identified on the card
websites: array - of the identified websites on the card. If no websites are identified then the array is empty. Each object in the array has the below fields:
- url: string - the URL identified for this website
addresses: array - of the identified addresses on the card. If no addresses are identified then the array is empty. Each object in the array has the below field:
- fullAddress: string - the full address identified
- parsedAddress: object - If the parseAddress option is set to true for a scan request and the user API key supports this functionality then the full address is broken into more specific segments. The fields of this object are:
  - street: string - the street of the address or null if none identified
  - postalCode: string - the postal code of the address or null if none identified
  - city: string - the city of the address or null if none identified
  - state: string - the state of the address or null if none identified
  - country: string - the country of the address or null if none identified
  - latitude: string - the latitude of the address
  - longitude: string - the longitude of the address
notes: string - this field is usually empty. This field is used in some European countries to include VAT or other popular numbers that are often found in cards from these countries.

Additional notes:

The Covve Scan solution is hosted on Microsoft Azure's West Europe data centres and is in compliance with GDPR.

The image and data of the cards are not stored on our servers. It is processed, returned to the customer and not persisted. The only data that is persisted is a log that a scan took place for the customer, the timestamp of the scan, the language of the text and a boolean result of the scan (success/fail).