fullcontact-go

FullContact Go Client

The official FullContact Golang Client Library for the FullContact V3 APIs.

Installation

To install FullContact Go client, use go get:

go get github.com/fullcontact/fullcontact-go/fc

Then, reference fullcontact-go in a Go program with import:

import fc "github.com/fullcontact/fullcontact-go/fc"

To update FullContact Go client to the latest version use:

go get -u github.com/fullcontact/fullcontact-go/fc

Working with FullContact Client

FullContact client supports v3 Enrich APIs which are super simplified to easily enrich Person and Company data. All the API requests are over HTTPS using POST method with content sent as JSON. This library supports Multi Field Request, Person Enrichment & Data Packs, Company Enrichment & Data Packs and Webhooks. Just build a FullContact Client with your API Key, make a enrich request and get a response object back.

Quick Overview

If you are not familiar with the Enrich API, complete details can be found @API documentation

FullContact Client provides an object layer to FullContact API communication, but understanding Enrich API, webhooks, request and response parameters, and common snags is still important.

Once you’re on board with the API behavior, FullContact Client library should simplify your integration.

Supported APIs

• Enrich
  • person.enrich
  • company.enrich
  • company.search
• Resolve
  • identity.map
  • identity.resolve
  • identity.delete

Providing Authentication to FullContact Client

FullContact client uses CredentialsProvider interface for Authentication. Different ways to provide authentication:

• Static API Key provider:

cp, err := fc.NewStaticCredentialsProvider("your-api-key")

• Through System Environment Variable:

//API Key is stored as Environment variable FC_API_KEY
cp, err := fc.NewDefaultCredentialsProvider("FC_API_KEY")

• If no CredentialsProvider is specified while making FullContact Client, it automatically looks for API key from Environment variable "FC_API_KEY"

(Don't have an API key? You can pick one up for free right here.)

Making a FullContact Client

Make your fcClient with:

Please note that you don't have to provide Authorization and Content-Type in the custom Headers map as these will be automatically added. Custom headers provided will remain same and will be sent with every request made with this client. If you wish to change the headers, make a new client with new custom headers.

RetryHandler

type RetryHandler interface {
	ShouldRetry(responseCode int) bool
	RetryAttempts() int
	RetryDelayMillis() int
}

In case of failure, FullContact Client will auto-retry for same request based on certain conditions set in RetryHandler

• Although optional, a custom Retry handler can be created by implementing RetryHandler interface and then be used to make FC client. By default, client will use DefaultRetryHandler to schedule a retry for same request, with retryAttempts = 1, retryDelayMillis = 1000, and in case of 429(rate limit error) or 503(capacity limit error).

• This Client will auto-retry for a maximum of 5 times, even if higher value is set in the custom Retry Handler.

fcClient, err := fc.NewFullContactClient(
		fc.WithCredentialsProvider(cp),
		fc.WithHeader(map[string]string{"Reporting-Key": "FC_GoClient_1.0.0"}),
		fc.WithTimeout(3000))

Enrich

Enrich API Reference

• person.enrich
• company.enrich
• company.search

Making a Person Enrich Request

Our V3 Person Enrich supports Multi Field Request: ability to match on one or many input fields

You can build a Person Request using NewPersonRequest and setting different input parameters that you have. If you want to use Webhook, you can specify it in webhookUrl field. API can lookup and enrich individuals by sending any identifiers you may already have, such as:

• Emails: []string
• Phones: []string
• Location: *Location
  • AddressLine1: string
  • AddressLine2: string
  • City: string
  • Region: string
  • RegionCode: string
  • PostalCode: string
• Name: *PersonName
  • Full: string
  • Given: string
  • Family: string
• Profiles: []*Profile
  • Service: string
  • Username: string
  • Userid: string
  • Url: string
• DataFilters: []string
• Maids: []string
• Confidence: string
• Infer: bool
• EebhookUrl: string
• RecordId: string
• PersonId: string

profile, err := fc.NewProfile(
		fc.WithUsername("bartlorang"),
		fc.WithService("twitter"))
if err != nil {
    log.Fatalln(err)
    return
}
personRequest, err := fc.NewPersonRequest(
    fc.WithEmail("bart@fullcontact.com"),
    fc.WithEmail("bart.lorang@fullcontact.com"),
    fc.WithName(&fc.PersonName{Full:"Bart Lorang",}),
    fc.WithLocation(fc.NewLocation(
        fc.WithAddressLine1("123 Main street"),
        fc.WithAddressLine1("Unit2"),
        fc.WithCity("Denver"),
        fc.WithRegionForLocation("Colorado"))),
    fc.WithProfile(profile),
    fc.WithWebhookUrl(""),
    fc.WithRecordId("customer123"),
    fc.WithPersonId("eYxWc0B-dKRxerTw_uQpxCssM_GyPaLErj0Eu3y2FrU6py1J"))

Person Enrich Request and Response

You can send a request by calling PersonEnrich on fcClient and passing personRequest as a argument. It sends a Asynchronous request and a channel of type APIResponse is returned as response. You can then receive response from this channel. There is a flag isSuccessful on APIResponse to check if the request was successful or not. If the request was unsuccessful, you can check the status code and message to determine the cause.

//Sending Person Enrich request which returns a channel of type `APIResponse`
ch := fcClient.PersonEnrich(personRequest)
resp := <-ch
fmt.Printf("Person Enrich API Response: %v", resp)
if resp.IsSuccessful == true {
    fmt.Printf("Person Response: %v", *resp.PersonResponse)
    fmt.Println(resp.PersonResponse.FullName)
}

Company Enrich Request and Response

To Enrich Company data FullContact library provides two methods Lookup by Company Domain or Search by Company Name. More data is available through the Lookup by Company Domain, but if the domain is unknown, use our Search by Company Name API to find the list of domains that could be related to the Company you are looking for and then call the Lookup by Company Domain with that domain to get the full information about the company.

Lookup by Company Domain

• Request:

companyEnrichRequest, err := fc.NewCompanyRequest(fc.WithDomain("fullcontact.com"))
if err != nil {
    log.Fatalln(err)
    return
}

• Response:

resp := <-fcClient.CompanyEnrich(companyEnrichRequest)
fmt.Printf("Company Enrich API Response: %v", resp)
if resp.IsSuccessful {
    fmt.Printf("Company Name: %v", resp.CompanyResponse.Name)
}

Search by Company Name

• Request:
  • Parameters:
    • companyName
    • webhookUrl
    • location
    • locality
    • region
    • country
    • sort

companySearchRequest, err := fc.NewCompanyRequest(fc.WithCompanyName("FullContact"))
if err != nil {
    log.Fatalln(err)
    return
}

• Response: It returns an array of CompanySearchResponse.

resp := <-fcClient.CompanySearch(companySearchRequest)
fmt.Printf("Company Search API Response: %v", resp)
if resp.IsSuccessful {
    fmt.Printf("Company Lookup Domain: %v", resp.CompanySearchResponse[0].LookupDomain)
}

Resolve

Resolve API Reference

• identity.map
• identity.resolve
• identity.delete

Resolve Request

Resolve uses ResolveRequest type for its request which supports Multi Field Request: ability to match on one or many input fields

You can build a Resolve Request by using NewResolveRequest and setting different input parameters that you have.

Note: For identity.map any of email, phone, profile, name & location must be present.

API can lookup and resolve individuals by sending any identifiers you may already have, such as:

• Emails: []string
• Phones: []string
• Location: *Location
  • AddressLine1: string
  • AddressLine2: string
  • City: string
  • Region: string
  • RegionCode: string
  • PostalCode: string
• Name: *PersonName
  • Full: string
  • Given: string
  • Family: string
• Profiles: []*Profile
  • Service: string
  • Username: string
  • Userid: string
  • Url: string
• Maids: []string
• RecordId: string
• PersonId: string

resolveRequest, err := fc.NewResolveRequest(
		fc.WithRecordIdForResolve("r1"),
		fc.WithEmailForResolve("bart@fullcontact.com"))

Resolve Response

All resolve methods returns a channel of type APIResponse from which you can get ResolveResponse

resp := <-fcClient.IdentityMap(resolveRequest)
fmt.Printf("Identity Map API Response: %v", resp)
if resp.IsSuccessful {
    fmt.Printf("RecordIds Mapped: %v", resp.ResolveResponse.RecordIds)
}
resp = <-fcClient.IdentityResolve(resolveRequest)
fmt.Printf("Identity Resolve API Response: %v", resp)
if resp.IsSuccessful {
    fmt.Printf("PersonIds Mapped: %v", resp.ResolveResponse.PersonIds)
}

resp = <-fcClient.IdentityDelete(resolveRequest)
fmt.Printf("Identity Delete API Response: %v", resp)
if resp.IsSuccessful {
    fmt.Println("Record Deleted Successfully!")
}