Integration

• REST API
• Custom domain

REST API

The documentation of the api can be found in Api Docs page. This article defines the resources available in the Vcards integration API.

Access token

In order to access the API it is required having an accessToken. Once you have an accessToken you must include it in every request as a HTTP header

AccessToken: "YOUR_API_KEY_HERE"

If you need to try different API calls you can do it from the same Api Docs page, by using the "authorize" button

List vcards

Retrieve a paginated list of vcards with optional filtering and search functionality.

Parameters:

Name	Type	Description	Required
query	string	Search a string in name, code, or SKU	No
filters[]	array	Filter by field values, can include multiple in the format filters[field-slug]=value. Example: filters[email]=mymail	No
page	string	Page number for pagination (default is 1)	No
limit	string	Number of items per page (default is 25)	No

• query: A string to search in the tag’s name, code, or SKU.
• filters[]: An array for filtering by specific field values. Multiple filters can be passed in the format filters[field-slug]=value.
• page: A string representing the page number for pagination.
• limit: A string representing the number of items per page.

Responses:

The response for this endpoint would contain a paginated list of tags with the applied filters and search criteria.

Create a new vcard

Creates a new vcard in the team.

Parameters ( values )

Name	Type	Description	Required
name	string	Full name ( contains name and last name )	Yes
collection	string	Brand id ( this value uniquely identifies a vcard brand )	Yes
position	object	Job Position as a localized value. Uses the locale as a key	No
email	string	Email related to the vcard	Yes
telephone	string	Phone number	No
mobile-phone	string	Mobile phone number	No
address	string	Address of the vcard	No
address-second-line	string	When the address is too long	No
department	string	Company department	No
postal-code	string	Postal code / zip code	No
city	string	City	No

• sku: A string representing the SKU (Stock Keeping Unit) used to identify the vcard to be updated.
• { [field-slug]: string }: A JSON object containing the vcard details. Each of the keys belongs to the slug of the field in the vcard.

Request Body:

• Media type: application/json
• Example request body:

  {
    "name": "John Doe",
    "collection": "{brand_id}",
    "values": {
      "position": {
        "en": "General Manager",
        "es": "Director General"
      },
      "email": "john.doe@domain.com",
      "telephone": "+1234567890",
      "mobile-phone": "+1234567890",
      "address": "1234 Main Street",
      "address-second-line": "Suite 123",
      "department": "Marketing",
      "postal-code": "08080",
      "city": "Barcelona"
    }
  }
  

Responses:

201 - Success

• Media type: application/json
• Example response:

  {
      "code": "BVHWSTMGL",
      "sku": "ABC000",
      "values": {
        "name": "Full name",
        "email": "john.doe@domain.com",
        "telephone": "+1234567890",
        "position": { 
          "en":  "CEO", 
          "es": "Director General" 
        },
        "mobile-phone": "+1234567890",
        "address": "1234 Main St, City, Country",
        "department" : "Marketing"
      }
  }
  
  

Show vcard detail

Retrieves vcard details by the given SKU. The SKU is a unique reference for the vcard.

Parameters:

Name	Type	Description	Required
sku	string	SKU code	Yes

• sku: A string representing the SKU (Stock Keeping Unit) used to retrieve specific vcard details.

Responses:

200 - Success

• Media type: application/json
• Example response:

  {
      "code": "BVHWSTMGL",
      "sku": "ABC000",
      "values": {
        "name": "Full name",
        "email": "john.doe@domain.com",
        "telephone": "+1234567890",
        "position": { 
          "en":  "CEO", 
          "es": "Director General" 
        },
        "mobile-phone": "+1234567890",
        "address": "1234 Main St, City, Country",
        "department" : "Marketing"
      }
  }
  

404 - Not Found

• Description: Vcard not found in the team for the given SKU.

Edit a vcard

Updates the details of an existing vcard identified by the SKU.

Attention: When a value is NOT included in the request body, that value will be ERASED!! Every PUT request must include all the fields that you want to keep.

Parameters:

Name	Type	Description	Required
sku	string	SKU code	Yes

• sku: A string representing the SKU (Stock Keeping Unit) used to identify the vcard to be updated.

Request Body:

• Media type: application/json
• Example request body:

   {
    "code": "BVHWSTMGL",
    "sku": "ABC000",
    "values": {
      "name": "Full name",
      "email": "john.doe@domain.com",
      "telephone": "+1234567890",
      "position": { 
        "en":  "CEO", 
        "es": "Director General" 
      },
      "mobile-phone": "+1234567890",
      "address": "1234 Main St, City, Country",
      "department" : "Marketing"
  
    }
  }
  

Responses:

200 - Success

• Media type: application/json

• Example response:

  {
      "code": "BVHWSTMGL",
      "sku": "ABC000",
      "values": {
        "name": "Full name",
        "email": "john.doe@domain.com",
        "telephone": "+1234567890",
        "position": { 
          "en":  "CEO", 
          "es": "Director General" 
        },
        "mobile-phone": "+1234567890",
        "address": "1234 Main St, City, Country",
        "department" : "Marketing"
      }
  }
  

• Description: Successful update of the vcard.

Delete a vcard

Deletes a vcard from the team by the given SKU.

Parameters:

Name	Type	Description	Required
sku	string	SKU code	Yes

• sku: A string representing the SKU (Stock Keeping Unit) used to delete the vcard.

Responses:

204 - Success

• Description: Vcard successfully deleted from the team.
• Media type: application/json

Custom domain

If you want use your own domain to access the vcards is very simple:

You need to add a DNS record of type "CNAME" in your own domain management tool

The records needs to have the following name and value:

Name: "{vcards}.yourdomain.com"
Value: vcards-go.tictap.me