POST api/v2/Users/{id}/UserCards/ReplaceCardIfExists
Adds a Card to an existing User. If the card is assigned to another user un-assigns it first. Returns Success/Error code plus primary key of UserCard entry made.
Request Information
URI Parameters
| Name | Description | Type | Additional information |
|---|---|---|---|
| id | string |
None. |
Body Parameters
ReplaceUserCardIfExistsViewModelV2| Name | Description | Type | Additional information |
|---|---|---|---|
| NumberOfCardUses |
Number of Card Uses |
integer |
None. |
| PublicNotes |
Public Notes |
string |
None. |
| CredentialTypeId |
Credential Type Id (optional) |
integer |
None. |
| UserId |
Required: The PK of the existing User that you want to add the card to. |
globally unique identifier |
None. |
| CardId |
Optional: The PK of an existing card that you want to assign to the User. Retrieve possible values from /Card/GetAllCards. If null, CardType, CardACSystem, InternalCardNumber, ExternalCardNumber and Facility code are required. |
globally unique identifier |
None. |
| CardType |
Conditional: If CardId is null, this is required. Represents the type of card being added dynamically. Retrieve possible values from /Card/GetAllCardTypes |
integer |
None. |
| CardACSystemId |
Conditional: If CardId is null, this is required. Represents the Access Control System of the card being added dynamically. Retrieve possible values from /ACSystem/GetAllSystems |
globally unique identifier |
None. |
| InternalCardNumber |
Conditional: If CardId is null, this is required. Represents the internal/encoded number of the card being added dynamically. |
integer |
None. |
| ExternalCardNumber |
Conditional: If CardId is null, this is required. Represents the external number printed on the card being added dynamically. |
string |
None. |
| CardSerialNumber |
Conditional: If CardType supports it, this is required. Represents the serial number of the smart card being added dynamically. |
integer |
None. |
| FacilityCode |
Conditional: If CardType supports it, this is required. Represents the facility code of the smart card being added dynamically. |
integer |
None. |
| IssueCode |
Conditional: If CardType supports it, this is required. Represents the issue code of the smart card being added dynamically. |
integer |
None. |
| PIN |
Optional: The PIN that the User may use in conjunction with this Card for Card + PIN mode or for when Readers are in PIN mode only. |
string |
None. |
| EnforceOccupancySystem |
Optional: Requests to verify if the CardACSystemId matches the system the User's Occupancy belongs to |
boolean |
None. |
| CardActivationStartDateTime |
Optional: Date and time of the card activation |
date |
None. |
| CardDeactivationStartDateTime |
Optional: Date and time of the card de-activation |
date |
None. |
| CardUserFlags |
Card User Flags |
CardUserFlags |
None. |
Request Formats
application/json, text/json
{
"NumberOfCardUses": 1,
"PublicNotes": "sample string 1",
"CredentialTypeId": 1,
"UserId": "c1ab3252-bbb0-4d7b-93ea-0ef8f1ae5f16",
"CardId": "73383e2f-0950-407c-88d0-9f83f1f6000e",
"CardType": 3,
"CardACSystemId": "5e995092-d363-4688-bc3a-fd8a2723a06e",
"InternalCardNumber": 4,
"ExternalCardNumber": "sample string 5",
"CardSerialNumber": 1,
"FacilityCode": 1,
"IssueCode": 1,
"PIN": "sample string 6",
"EnforceOccupancySystem": true,
"CardActivationStartDateTime": "2025-11-21T10:51:29.9415717+00:00",
"CardDeactivationStartDateTime": "2025-11-21T10:51:29.9415717+00:00",
"CardUserFlags": 1
}
application/xml, text/xml
<ReplaceUserCardIfExistsViewModelV2 xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/APIWebRole.Controllers"> <CardACSystemId>5e995092-d363-4688-bc3a-fd8a2723a06e</CardACSystemId> <CardActivationStartDateTime>2025-11-21T10:51:29.9415717+00:00</CardActivationStartDateTime> <CardDeactivationStartDateTime>2025-11-21T10:51:29.9415717+00:00</CardDeactivationStartDateTime> <CardId>73383e2f-0950-407c-88d0-9f83f1f6000e</CardId> <CardSerialNumber>1</CardSerialNumber> <CardType>3</CardType> <CardUserFlags>ActiveCardholderRecord</CardUserFlags> <EnforceOccupancySystem>true</EnforceOccupancySystem> <ExternalCardNumber>sample string 5</ExternalCardNumber> <FacilityCode>1</FacilityCode> <InternalCardNumber>4</InternalCardNumber> <IssueCode>1</IssueCode> <PIN>sample string 6</PIN> <UserId>c1ab3252-bbb0-4d7b-93ea-0ef8f1ae5f16</UserId> <CredentialTypeId>1</CredentialTypeId> <NumberOfCardUses>1</NumberOfCardUses> <PublicNotes>sample string 1</PublicNotes> </ReplaceUserCardIfExistsViewModelV2>
application/x-www-form-urlencoded
Sample not available.
Response Information
Resource Description
ReplaceCardIfExistsResult| Name | Description | Type | Additional information |
|---|---|---|---|
| PreviousUserId |
Represents a UserId for a user the card previously belonged to |
globally unique identifier |
None. |
| CurrentUserId |
Represents a UserId for a user the card has been assigned to |
globally unique identifier |
None. |
| ExternalCardNumber |
Represents the serial number of the smart card being added dynamically |
string |
None. |
| InternalCardNumber |
Represents the internal/encoded number of the card being added dynamically. |
integer |
None. |
| FacilityCode |
Represents the facility code of the smart card being added dynamically. |
integer |
None. |
| CardType |
Represents the type of card being added dynamically. Retrieve possible values from /Card/GetAllCardTypes |
integer |
None. |
| Value |
Represents the PK value that was created as a result of an add |
globally unique identifier |
None. |
| ResultCode |
Represents the result code |
integer |
None. |
| Description |
Represents a description of the result code |
string |
None. |
Response Formats
application/json, text/json
{
"PreviousUserId": "3e9c4801-6d5b-4abe-b687-b2a06b4cb7b1",
"CurrentUserId": "1a891b35-e72a-452a-b384-a3f53c0a8199",
"ExternalCardNumber": "sample string 1",
"InternalCardNumber": 1,
"FacilityCode": 1,
"CardType": 1,
"Value": "544dad6c-703e-4336-a32a-29661b442a62",
"ResultCode": 3,
"Description": "sample string 4"
}
application/xml, text/xml
<ReplaceCardIfExistsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/APIWebRole.Controllers"> <Description>sample string 4</Description> <HttpStatusCode>Continue</HttpStatusCode> <ResultCode>3</ResultCode> <Value>544dad6c-703e-4336-a32a-29661b442a62</Value> <CardType>1</CardType> <CurrentUserId>1a891b35-e72a-452a-b384-a3f53c0a8199</CurrentUserId> <ExternalCardNumber>sample string 1</ExternalCardNumber> <FacilityCode>1</FacilityCode> <InternalCardNumber>1</InternalCardNumber> <PreviousUserId>3e9c4801-6d5b-4abe-b687-b2a06b4cb7b1</PreviousUserId> </ReplaceCardIfExistsResult>