Foreign IDs

Abound enables developers to associate an Abound record with a unique, customer-specific ID, known as a foreignId. This allows developers to forego making their own tables every time they integrate and/or add an app.

📘

Foreign ID Support

We currently only offer this service to our Users, Payers, Expenses, and Incomes endpoints. If you believe that there is a great use case for another endpoint, we would love to hear from you! Contact [email protected].

Examples

Foreign IDs are always located at the root of our data object. In our example, we will be using the Users endpoint, but you can expect this to work the same for all other supported endpoints.

Here is an example of creating a User with a foreignId:

curl \
  --request POST \
  --url https://sandbox-api.withabound.com/v2/users \
  --header 'Authorization: Bearer <<apiKey>>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "email": "[email protected]",
      "foreignId": "your_foreign_id",
      "profile": {
        "firstName": "Sam",
        "lastName": "Wilson",
        "address": "1500 Pennsylvania Ave NW",
        "address2": "Suite 1776",
        "city": "Washington",
        "state": "DC",
        "zipcode": "20220",
        "phoneNumber": "2026229979",
        "dateOfBirth": "1776-07-04",
        "socialSecurityNumber": "123456789"
      }
    }
  }'
const { default: Abound, Environment } = require("@withabound/node-sdk");

const abound = new Abound({
  appId: "<<sandbox_app_id>>",
  appSecret: "<<sandbox_app_secret>>",
  environment: Environment.SANDBOX,
  apiVersion: "v2",
});

(async () => {
  const response = await abound.users.create({
    email: "[email protected]",
    foreignId: "your_foreign_id",
    profile: {
      firstName: "Sam",
      lastName: "Wilson",
      address: "1500 Pennsylvania Ave NW",
      address2: "Suite 1776",
      city: "Washington",
      state: "DC",
      zipcode: "20220",
      phoneNumber: "2026229979",
      dateOfBirth: "1776-07-04",
      socialSecurityNumber: "123456789",
    },
  });

  console.log(response);
})();
import requests

url = "https://sandbox-api.withabound.com/v2/users"

payload = {"user": {
        "profile": {
            "firstName": "Sam",
            "lastName": "Wilson",
            "address": "1500 Pennsylvania Ave NW",
            "address2": "Suite 1776",
            "city": "Washington",
            "state": "DC",
            "zipcode": "20220",
            "phoneNumber": "2026229979",
            "dateOfBirth": "1776-07-04",
            "socialSecurityNumber": "123456789"
        },
        "email": "[email protected]",
        "foreignId": "your_foreign_id"
    }}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer <<apiKey>>"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
// import com.squareup.okhttp.*;
// import com.google.gson.JsonObject;

OkHttpClient client = new OkHttpClient();

JsonObject requestBody = new JsonObject();
JsonObject user = new JsonObject();
JsonObject profile = new JsonObject();

user.addProperty("email", "[email protected]");
user.addProperty("foreignId", "your_foreign_id");

profile.addProperty("firstName", "Sam");
profile.addProperty("lastName", "Wilson");
profile.addProperty("addPropertyress", "1500 Pennsylvania Ave NW");
profile.addProperty("addPropertyress2", "Suite 1776");
profile.addProperty("city", "Washington");
profile.addProperty("state", "DC");
profile.addProperty("zipcode", "20220");
profile.addProperty("phoneNumber", "2026229979");
profile.addProperty("dateOfBirth", "1776-07-04");
profile.addProperty("socialSecurityNumber", "123456789");

user.add("profile", profile);

requestBody.add("user", user);

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, requestBody.toString());
Request request = new Request.Builder()
  .url("https://sandbox-api.withabound.com/v2/users")
  .post(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer <<apiKey>>")
  .build();

Response response = client.newCall(request).execute();
package main

import (
    "bytes"
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://sandbox-api.withabound.com/v2/users"

    var requestBody = []byte(`{
        "user": {
            "email": "[email protected]",
            "foreignId": "your_foreign_id",
            "profile": {
                "firstName": "Sam",
                "lastName": "Wilson",
                "address": "1500 Pennsylvania Ave NW",
                "address2": "Suite 1776",
                "city": "Washington",
                "state": "DC",
                "zipcode": "20220",
                "phoneNumber": "2026229979",
                "dateOfBirth": "1776-07-04",
                "socialSecurityNumber": "123456789"
            }
        }
    }`)

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(requestBody))

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Authorization", "Bearer <<apiKey>>")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}
// using RestSharp;

var client = new RestClient("https://sandbox-api.withabound.com/v2/users");
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer <<apiKey>>");
request.AddJsonBody(new {
  user = new {
    email = "[email protected]",
    foreignId = "your_foreign_id",
    profile = new {
      firstName =  "Sam",
      lastName = "Wilson",
      address = "1500 Pennsylvania Ave NW",
      address2 = "Suite 1776",
      city = "Washington",
      state = "DC",
      zipcode = "20220",
      phoneNumber = "2026229979",
      dateOfBirth = "1776-07-04",
      socialSecurityNumber = "123456789"
    }
  }
});
IRestResponse response = client.Execute(request);
require 'uri'
require 'net/http'
require 'openssl'
require 'json'

url = URI("https://sandbox-api.withabound.com/v2/users")
requestBody = {
  user: {
    email: '[email protected]',
    foreignId: 'your_foreign_id',
    profile: {
      firstName: 'Sam',
      lastName: 'Wilson',
      address: '1500 Pennsylvania Ave NW',
      address2: 'Suite 1776',
      city: 'Washington',
      state: 'DC',
      zipcode: '20220',
      phoneNumber: '2026229979',
      dateOfBirth: '1776-07-04',
      socialSecurityNumber: '123456789'
    }
  }
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Bearer <<apiKey>>'
request.body = requestBody.to_json

response = http.request(request)
puts response.read_body

Next, here is an example of updating the foreignId on an existing User:

curl \
  --request PUT \
  --url https://sandbox-api.withabound.com/v2/users/<<testUserId>> \
  --header 'Authorization: Bearer <<apiKey>>' \
  --header 'Content-Type: application/json' \
  --data '{
    "user": {
      "email": "[email protected]",
      "foreignId": "your_foreign_id"
    }
  }'
const { default: Abound, Environment } = require("@withabound/node-sdk");

const abound = new Abound({
  appId: "<<sandbox_app_id>>",
  appSecret: "<<sandbox_app_secret>>",
  environment: Environment.SANDBOX,
  apiVersion: "v2",
});

(async () => {
  const response = await abound.users.update(
    "<<testUserId>>",
    {
      email: "[email protected]",
      foreignId: "your_foreign_id",
    }
  );

  console.log(response);
})();
import requests

url = "https://sandbox-api.withabound.com/v2/users/<<testUserId>>"

payload = {"user": {
        "email": "[email protected]",
        "foreignId": "your_foreign_id"
    }}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": "Bearer <<apiKey>>"
}

response = requests.request("PUT", url, json=payload, headers=headers)

print(response.text)
// import com.squareup.okhttp.*;
// import com.google.gson.JsonObject;

OkHttpClient client = new OkHttpClient();

JsonObject requestBody = new JsonObject();
JsonObject user = new JsonObject();

user.addProperty("email", "[email protected]");
user.addProperty("foreignId", "your_foreign_id");

requestBody.add("user", user);

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, requestBody.toString());
Request request = new Request.Builder()
  .url("https://sandbox-api.withabound.com/v2/users/<<testUserId>>")
  .put(body)
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer <<apiKey>>")
  .build();

Response response = client.newCall(request).execute();
package main

import (
    "bytes"
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://sandbox-api.withabound.com/v2/users/<<testUserId>>"

    var requestBody = []byte(`{
        "user": {
            "email": "[email protected]",
            "foreignId": "your_foreign_id"
        }
    }`)

    req, _ := http.NewRequest("PUT", url, bytes.NewBuffer(requestBody))

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Content-Type", "application/json")
    req.Header.Add("Authorization", "Bearer <<apiKey>>")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}
// using RestSharp;

var client = new RestClient("https://sandbox-api.withabound.com/v2/users");
var request = new RestRequest(Method.PUT);
request.AddHeader("Accept", "application/json");
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer <<apiKey>>");
request.AddJsonBody(new {
  user = new {
    email = "[email protected]",
    foreignId = "your_foreign_id"
  }
});
IRestResponse response = client.Execute(request);
require 'uri'
require 'net/http'
require 'openssl'
require 'json'

url = URI("https://sandbox-api.withabound.com/v2/users/<<testUserId>>")
requestBody = {
  user: {
    email: '[email protected]',
    foreignId: 'your_foreign_id'
  }
}

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request["Authorization"] = 'Bearer <<apiKey>>'
request.body = requestBody.to_json

response = http.request(request)
puts response.read_body

And finally, here is an example of retrieving a User with the foreignId query parameter filter:

curl \
  --request GET \
  --url 'https://sandbox-api.withabound.com/v2/users?foreignId=your_foreign_id' \
  --header 'Authorization: Bearer <<apiKey>>'
const { default: Abound, Environment } = require("@withabound/node-sdk");

const abound = new Abound({
  appId: "<<sandbox_app_id>>",
  appSecret: "<<sandbox_app_secret>>",
  environment: Environment.SANDBOX,
  apiVersion: "v2",
});

(async () => {
  const response = await abound.users.list({
    foreignId: "your_foreign_id",
  });

  console.log(response);
})();
import requests

url = "https://sandbox-api.withabound.com/v2/users"

querystring = {"foreignId":"your_foreign_id"}

headers = {
    "Accept": "application/json",
    "Authorization": "Bearer <<apiKey>>"
}

response = requests.request("GET", url, headers=headers, params=querystring)

print(response.text)
// import com.squareup.okhttp.*;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://sandbox-api.withabound.com/v2/users?foreignId=your_foreign_id")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer <<apiKey>>")
  .build();

Response response = client.newCall(request).execute();
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "https://sandbox-api.withabound.com/v2/users?foreignId=your_foreign_id"

    req, _ := http.NewRequest("GET", url, nil)

    req.Header.Add("Accept", "application/json")
    req.Header.Add("Authorization", "Bearer <<apiKey>>")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}
// using RestSharp;

var client = new RestClient("https://sandbox-api.withabound.com/v2/users?foreignId=your_foreign_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept", "application/json");
request.AddHeader("Authorization", "Bearer <<apiKey>>");
IRestResponse response = client.Execute(request);
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://sandbox-api.withabound.com/v2/users?foreignId=your_foreign_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["Authorization"] = 'Bearer <<apiKey>>'

response = http.request(request)
puts response.read_body

Did this page help you?