Some contact features do not have a Console or Portal screen, so you use the CRM API to work with them. This reference covers linking a contact to their spouse, finding a contact by secondary email address, finding a contact by number, and seeing who named a contact as their Portal delegate. For each lookup, the API only returns a contact when the matching value, such as an email address, is stored on that contact’s Rhythm record. Being recognized somewhere else, such as during Portal sign-in, does not make a contact searchable by that value.
Linking a Contact to Their Spouse
You can record a person’s spouse by updating the contact through the API. Spouse is a dedicated contact field that this API call manages. It is separate from the general Relationships feature, so creating a relationship record between two contacts, even with a relationship type named "Spouse," does not fill the spouse fields or make the contacts appear in a query for a contact’s spouse. These rules apply:
| Rule | What happens if you break it |
|---|---|
| The spouse must already exist as a contact in your Rhythm account | The save is refused |
| A contact cannot be its own spouse | The save is refused as invalid |
| The pairing is not automatically symmetrical | Setting Contact A’s spouse to Contact B does not set Contact B’s spouse to Contact A, so update both records if you want the relationship to show both ways |
| A contact who is named as anyone’s spouse cannot be deleted | The delete is refused until you remove the spouse reference |
Finding a Contact by a Secondary Email Address
Each contact can have more than one email address on file. You can use the API to find contacts that use a specific second or third email address through the email_address2 and email_address3 fields. The match is exact and case-sensitive, so an address with uppercase letters or extra spaces will not be found. Enter the address exactly as it is stored: lowercase, with no leading or trailing spaces.
Finding a Contact by Its Number
Each contact has a number. You can use the API to find the one contact with a specific number. This lookup is not available from the Portal because it is for staff-side integrations only. You can add a fields parameter to the request to receive only the fields you name. Because some past responses did not consistently honor this parameter, confirm that the fields you asked for came back before relying on it.
Finding Who Named a Contact as Their Portal Delegate
A Portal member can name another contact as their delegate. You can use the API to see which contacts named a specific contact as their delegate. The results include expired delegations, so check each result’s expiry if you only need current delegations. This lookup is also not available from the Portal.
Endpoint Path Parameters
Reach these lookups by putting the value you are searching for directly in the request path, in place of the parameter name below.
| Lookup | Path parameter | What it matches |
|---|---|---|
| Contact by number | number | The contact’s assigned number |
| Contact by secondary email | email_address2 | The contact’s second email address, matched exactly |
| Contact by third email | email_address3 | The contact’s third email address, matched exactly |
| Portal delegate | portal_delegate_id | The identifier of the delegate contact |
The API documentation also lists the contact’s profile photo as the image_url field, if you need to read or set it directly instead of using the Console.
How Contact Identifiers Are Assigned
Rhythm assigns every contact’s record identifier automatically, and the format depends on how the contact was created. A contact created in the Console typically gets a short, integer-style identifier that matches its number. A contact created through the Portal, or brought in by an import, can get an alphanumeric identifier instead. There is no setting to standardize this format or to force Portal-created contacts to receive an integer identifier.
Warning
A contact’s record identifier and its number are assigned independently, and the identifier’s format is not guaranteed. If you see an alphanumeric value where you expected a number, or a number where you expected an alphanumeric value, both still identify the same contact, and either can be used to look up or link to that record.
When you run a mass update against contact records, use the contact’s actual record identifier. An identifier copied from a membership-style search result with a contact: prefix is not a valid contact identifier for this purpose. Remove the prefix before you upload the file.
Contact and organization record identifiers are unique across your whole account. An identifier used by one contact is never also used by an organization.